唯一正解是执行 composer config bitbucket-oauth bitbucket.org ，需使用个人账号生成的、含 repository:read 权限的 Bitbucket App Password，配置后自动写入 auth.json 并生效。
composer config bitbucket-oauth 是唯一正解
Composer 下载私有 Bitbucket 仓库包失败（比如 Could not fetch https://api.bitbucket.org/2.0/repositories/xxx/yyy, enter your bitbucket credentials），根本原因是没配认证，而 composer config bitbucket-oauth 就是专门干这事的命令，别去动 auth.json 手动写或改全局配置路径。
它会自动把 token 写进当前项目根目录的 auth.json（若存在）或用户级 ~/.composer/auth.json，且自动加锁、校验格式，比手写安全得多。
- 必须用 Bitbucket App Password（不是账号密码），且权限至少勾选
repository:read - 域名必须写
bitbucket.org，不能带https://或斜杠 - 执行后不会回显密码，但可用
composer config --auth --list验证是否写入成功
App Password 怎么生成才有效
Bitbucket Cloud 的个人账号密码 Composer 不认，必须用 App Password——而且得开对权限、选对账户层级。
- 登录 bitbucket.org → 右上头像 →
Personal settings→App passwords→Create app password - 名称随便填（比如
composer-cli），但权限务必勾选：Repositories: Read（下载私有库必需），Account: Read（部分旧版 Composer 会校验） - 生成后立刻复制保存，页面刷新就再也看不到了；如果提示
This app password has been revoked，说明你删过或重生成了，得换新的 - 别用团队账号生成 App Password——Composer 认的是发起请求的用户身份，必须用实际拥有仓库读权限的个人账号来建
为什么 composer install 还报 401 或 403
配完 bitbucket-oauth 还报错，大概率是缓存、作用域或路径搞错了。
- 运行
composer clear-cache，否则 Composer 可能复用旧的未授权请求头 - 确认
composer.json里私有包的repository类型是vcs，且 URL 是https://bitbucket.org/owner/repo.git格式（不是 SSH 或 API 地址） - 如果在 CI 环境（如 GitHub Actions），
composer config写的是本地用户目录，得显式指定--global或用环境变量COMPOSER_AUTH注入 JSON 字符串 - Bitbucket Server（自建版）不支持
bitbucket-oauth，得走http-basic+ Basic Auth，别混用
private-packagist 或其他镜像下还能用吗
不能。一旦用了 Packagist 的镜像服务（比如 Private Packagist、Satis），所有包元数据都走镜像源，但私有 Bitbucket 包的代码拉取仍由 Composer 直连 Bitbucket——所以镜像配置和 bitbucket-oauth 是两件事，互不替代。
- 镜像只管“告诉 Composer 有哪些包、版本号是多少”，不代理 git clone
- 即使配置了镜像，只要
composer.json中某个包的source指向 Bitbucket，就必须本地有对应bitbucket-oauth - 某些企业镜像支持“上游凭据透传”，那是镜像服务自己的功能，跟 Composer 原生命令无关，得查对应文档
最常被忽略的一点：App Password 权限改了、过期了、或者仓库从私有变公开又改回去，都会导致已有 token 失效——别只盯着配置命令，先确认凭证本身还活着。
