根本原因是未配置bitbucket-oauth；必须用Bitbucket App Password（含repository:read权限）填入auth.json的"bitbucket-oauth"键下，域名严格为bitbucket.org，且Composer版本需≥2.2。
Composer 无法拉取私有 Bitbucket 仓库，根本原因是没配 bitbucket-oauth；配了但无效，大概率是 token 权限不足、域名写错，或用了 SSO 账户却没关双因素（2FA）强制要求。
bitbucket-oauth 是什么，为什么必须手动配置
bitbucket-oauth 是 Composer 在 auth.json 中识别 Bitbucket OAuth 认证的固定键名，不是任意自定义字段。Composer 用它向 Bitbucket API 发起请求时携带 Authorization: Bearer <token></token>，绕过密码登录限制。Bitbucket Cloud 已停用密码认证（HTTP Basic Auth），仅支持 OAuth2 或 App Password —— 而 Composer 官方只原生支持 bitbucket-oauth 这一种方式对接。
常见错误现象：Could not fetch https://api.bitbucket.org/2.0/repositories/xxx/yyy, enter your bitbucket.org credentials，或直接报 401 Unauthorized。
- 不配置
bitbucket-oauth→ 私有仓库完全不可访问 - 配置了但值为空、格式错误、或用了个人密码 → 仍会触发交互式登录或失败
- 用企业版 Bitbucket Server（非 Cloud）→ 此配置无效，需改用
http-basic或自定义 VCS 类型
生成合法 App Password 并填入 auth.json
Bitbucket Cloud 不再允许用账户密码，必须用 App Password（本质是 OAuth2 token 的简化替代）。它必须带 repository:read 权限，且不能绑定 SSO —— 如果你的账号启用了 SSO，App Password 将被禁用，必须先在 Bitbucket 设置中关闭 SSO 或联系管理员授权。
操作路径：Bitbucket → 个人头像 → Personal settings → App passwords → Create app password → 勾选 repository:read（其他权限按需），保存后复制完整字符串。
将该字符串填入全局或项目级 auth.json：
{
"bitbucket-oauth": {
"bitbucket.org": "app_password_here"
}
}
-
auth.json默认位置：~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows） - 若项目内已有
auth.json，Composer 会优先读取它（注意 Git 忽略该文件！） - 值必须是纯字符串，不能带引号外的空格、换行或注释
- 域名必须写
bitbucket.org，写www.bitbucket.org或https://bitbucket.org均无效
验证是否生效 + 常见兼容性坑
运行 composer diagnose 只能检查 JSON 格式和基础连接，不能验证 OAuth 是否真正可用。真实验证方式是执行一次私有包安装：
composer require vendor/private-package:dev-main
若仍失败，重点排查以下三点：
- Composer 版本低于 2.2？旧版对 Bitbucket API v2 支持不稳定，升级到
^2.5更稳妥：composer self-update - Bitbucket 仓库 URL 是
git@bitbucket.org:xxx/yyy.git？Composer 默认走 HTTPS，需确保composer.json中repositories类型为vcs且 URL 以https://开头 - 公司网络拦截了
api.bitbucket.org？可临时用curl -H "Authorization: Bearer xxx" https://api.bitbucket.org/2.0/user测试 token 是否被接受
最易被忽略的一点：App Password 一旦生成就不可再查看，删掉就得重做；而 Composer 缓存可能保留失败的认证状态，遇到诡异 401，记得清缓存：composer clear-cache。另外，Bitbucket 的 rate limit 很紧（每小时 1000 次），高频调试时容易触发，错误信息却是模糊的 403，别被误导成权限问题。
