必须配 composer config bitbucket-oauth.bitbucket.org，否则私有包拉取必报403或“Could not fetch”；因Composer 2+已弃用OAuth consumer和http-basic，仅认bitbucket-oauth配置项，且域名须严格为bitbucket.org、App Password需个人账号生成并勾选Repositories: Read权限，配合vcs类型仓库URL（含.git）及正确包名方可生效。
必须配 composer config bitbucket-oauth.bitbucket.org，否则所有私有包拉取都会 403 或卡在 Could not fetch https://api.bitbucket.org/2.0/repositories/...。
为什么 bitbucket-oauth 是唯一有效入口
Composer 2+ 完全弃用了旧版 OAuth consumer 和 HTTP BasicAuth（http-basic.bitbucket.org 已不生效），只认 bitbucket-oauth 配置项。它不是可选项，是 Bitbucket 私有仓库的强制认证通道。
- 填错域名（比如写成
www.bitbucket.org或api.bitbucket.org）会导致配置静默失效 - token 权限不足（没勾
Repositories: Read）会报 403，但错误信息里完全不提示权限问题 - 用团队账号生成 App Password，而实际仓库归属个人账号——Composer 按 token 绑定的用户身份校验权限，不看组织关系
composer.json 中声明私有仓库的正确写法
即使 bitbucket-oauth 配好了，require 里直接写包名，或 repositories 里漏掉 "type": "vcs"，Composer 仍当普通包处理，完全不触发认证流程。
- URL 必须以
.git结尾：https://bitbucket.org/vendor/package.git，不能是网页地址 -
type字段必须显式设为vcs，不能留空、不能写package或git - 分支名要真实存在，比如
"dev-main"对应远程origin/dev-main，不是标签也不是本地分支 - 推荐用 SSH：
"url": "git@bitbucket.org:vendor/package.git"，前提是ssh -T git@bitbucket.org能通
App Password 怎么生成才真正可用
Bitbucket 不再接受账号密码直连，必须用 App Password，且生成时细节决定成败。
- 入口路径：右上头像 → Personal settings → App passwords → Create app password
- 名称随意（如
composer-read-private），但权限至少勾选Repositories: Read；Account: Read可选，部分 Composer 版本会校验 - 生成后页面只显示一次，关闭即不可恢复——复制完立刻存到安全地方
- 别用 Workspace 级别的 App Password，必须用拥有目标仓库读权限的个人账号创建
调试时最容易忽略的三个点
很多问题表面是“配了没用”，其实是被这些隐性条件卡住：
-
auth.json文件权限不是600，某些系统会拒绝读取（尤其 CI 环境） - 项目根目录下已有
auth.json，但里面混着旧的http-basic配置，Composer 会优先读它并忽略新bitbucket-oauth - 私有包自己的
composer.json里没定义name，或者name和require里写的不一致（大小写敏感）
