Composer提示无法连接到Bitbucket仓库_配置OAuth凭证或SSH【连接指南】

Composer连不上Bitbucket私有仓库？九成是认证配置“打架”了

Composer连不上Bitbucket私有仓库主因是认证配置混乱：必须统一用bitbucket-oauth（配App Password）或http-basic，不可混用；URL须为HTTPS+vcs+.git后缀；包名须与仓库composer.json中name完全一致；CI推荐用COMPOSER_AUTH环境变量；报错先清缓存再-vvv查Authorization头。

遇到Composer死活连不上Bitbucket私有仓库的情况，先别急着怀疑网络。经验表明，十次有九次，问题都出在认证方式的“内耗”上——bitbucket-oauth和http-basic这两条路不能混着走，SSH和HTTPS也不会自动切换。解决问题的关键，在于先选定一条路，然后把配置项、URL格式、权限和缓存状态，严丝合缝地对齐。

配置bitbucket-oauth，必须用App Password，而非账号密码

这里有个常见的误区：Bitbucket Cloud早已不接受主账号密码直接认证，旧版的OAuth consumer也已失效。现在唯一认的，是你个人账号下生成的App Password，并且生成时务必勾选Repositories: Read权限。这个密码属于“过时不候”，只显示一次，复制后必须立刻保存，刷新页面就再也找不回来了。

• 标准操作是执行命令：composer config --global bitbucket-oauth.bitbucket.org 。这是最稳妥的方式，不建议手动编辑auth.json文件，容易出错。
• 域名必须精确到bitbucket.org，写成www.bitbucket.org或api.bitbucket.org都会导致配置无效。
• 命令执行后通常没有回显，可以用composer config --auth --list来确认是否写入成功。
• 如果后续操作提示This app password has been revoked，那说明这个密码已被删除或重新生成，需要配置一个新的。

repositories中的URL：必须是HTTPS + vcs类型，且带.git后缀

即便bitbucket-oauth配得再正确，如果composer.json里repositories的URL格式不对，一切也是白搭。比如写成https://bitbucket.org/xxx/yyy（缺少.git后缀），或者直接把仓库地址塞进require里，Composer都不会触发认证流程，而是按匿名请求处理，结果自然是收到Could not fetch https://api.bitbucket.org/2.0/repositories/...这类错误。

• 正确的写法是：{"type": "vcs", "url": "https://bitbucket.org/username/repo.git"}
• URL必须是完整的Git克隆地址，带.git后缀，而不是浏览器里打开的页面地址。
• 包名（即require中写的vendor/name）必须与私有仓库内composer.json的name字段完全一致，包括大小写。
• 切忌混用：如果你配置了bitbucket-oauth，却用了SSH地址（如git@bitbucket.org:xxx/yyy.git），认证同样会失效。

走HTTP Basic Auth？那得用http-basic，不是bitbucket-oauth

如果你看到有些教程使用了http-basic.bitbucket.org，请注意，这是另一套独立的认证路径。它要求你在auth.json里手动填写username和password，而这里的password依然是App Password。关键在于，这套机制与bitbucket-oauth命令是互斥的，不能共存。如果同时存在，Composer会优先采用http-basic的配置，而忽略掉bitbucket-oauth。

• 全局设置Basic Auth的命令是：composer config --global http-basic.bitbucket.org username your-app-password
• 该命令会在auth.json中生成类似{"bitbucket.org": {"http-basic": {"bitbucket.org": {"username": "...", "password": "..."}}}}的结构。
• 记住，用了http-basic，bitbucket-oauth就失效；反之亦然，二者只能选其一。
• 对于CI/CD环境，更推荐使用COMPOSER_AUTH环境变量来注入整个auth.json的内容，这样可以有效避免因磁盘写权限导致的问题。

遇到401/403错误？先清缓存，再查日志里的Authorization头

Composer有个“固执”的习惯：它会缓存未授权的响应。这意味着，即便你刚刚配好了正确的凭证，它也可能执着地复用之前失败的请求头。不清理缓存，重试多少次都是徒劳。

• 第一步，永远是执行composer clear-cache，把旧的缓存清理干净。
• 第二步，带上-vvv参数运行命令，例如composer install -vvv 2>&1 | grep -i authorization，仔细查看输出日志，确认请求是否携带了Authorization: Basic ...或Authorization: Bearer ...这样的头部信息。
• 如果日志里根本没有Authorization头，那问题很可能出在repositories的URL格式错误、type没设成vcs，或者包名不匹配。
• 如果Authorization头已经发出，但依然返回403，那就需要重点检查App Password的权限是否包含了Repositories: Read，或者是否错误地使用了团队账号生成的密码（必须使用拥有仓库读权限的个人账号）。

最后，有两个特别容易混淆的点值得警惕：Bitbucket Server（自建版本）根本不支持bitbucket-oauth，只能走http-basic路径；另外，使用Packagist镜像服务与配置Bitbucket认证是两码事——镜像只负责加速元数据获取，实际拉取私有仓库代码时，仍需直连Bitbucket并完成认证，这一步省不了。