Composer拉取私有Bitbucket仓库需显式配置认证：推荐SSH方式（用ssh://URL、确保ssh-agent加载密钥）或HTTPS+App Password（通过auth.json注入凭据），避免协议混淆与缓存干扰。
Composer 能拉取私有 Bitbucket 仓库，但默认会失败——它不读取你本地 git 的凭据，也不自动复用 SSH 密钥，必须显式配置认证方式。
使用 SSH URL 并确保 SSH agent 已加载密钥
这是最稳定的方式，前提是你的 Bitbucket 账户已绑定对应公钥，且本地 ssh-agent 正在运行并已添加私钥。
- 在
composer.json中用ssh://格式声明仓库："repositories": [ { "type": "vcs", "url": "ssh://git@bitbucket.org:your-org/your-private-repo.git" } ] - 确认能手动克隆：
git clone ssh://git@bitbucket.org:your-org/your-private-repo.git，失败则先修复 SSH 连接（比如运行ssh-add ~/.ssh/id_rsa） - 注意 URL 中的冒号
:是 SSH 路径分隔符，不是/；写成git@bitbucket.org/your-org/...（HTTPS 风格）会导致 Composer 解析为 HTTPS 协议并跳过 SSH
使用 HTTPS + Bitbucket App Password（推荐用于 CI 或无 SSH 环境）
Bitbucket Cloud 已停用账户密码登录 Git，必须用「App Password」代替。Composer 本身不支持交互式输入密码，所以得把凭据硬编码进 URL 或通过 auth.json 注入。
- 生成 App Password：进入 Bitbucket 设置 → «App passwords» → 创建，勾选
repository:read（或更细粒度权限） - 在
composer.json中使用带凭据的 HTTPS URL（仅限开发机，勿提交）："url": "https://<your-username>:<your-app-password>@bitbucket.org/your-org/your-private-repo.git"
- 更安全的做法是写入项目根目录的
auth.json（该文件默认被 Composer 加载，且应加到.gitignore）：{ "bitbucket.org": { "consumer-key": "<your-username>", "consumer-secret": "<your-app-password>" } }注意：这里字段名是历史遗留，实际填的是用户名和 App Password，不是 OAuth key/secret
避免踩坑：Composer 的协议降级与缓存干扰
Composer 在解析 VCS 包时，会尝试多种协议（如先试 HTTPS，再试 SSH），若配置混乱，可能静默回退到公开镜像或报错 Could not fetch，而不是明确提示认证失败。
- 运行
composer clear-cache再composer update -vvv，观察日志里实际使用的 URL 和协议 - 如果看到
Cloning to cache at ...后卡住或失败，大概率是缓存中已有错误的匿名 clone 尝试，清缓存+删vendor/再试 - 不要在
repositories里混用type: "package"和type: "vcs"指向同一仓库，否则 Composer 可能忽略 VCS 配置而走 package 的静态定义，绕过认证逻辑
最关键的一点：Composer 不继承 shell 的 git 配置，也不读 ~/.netrc（除非你额外启用 git config --global credential.helper store 并配合 auth.json 的 HTTPS 凭据）。想让私有仓库稳定工作，要么走 SSH（依赖系统级 SSH 设置），要么走 HTTPS + 显式凭据（依赖 auth.json 或 URL 内联），没有中间态。
