composer拉取私有Bitbucket仓库需确保ssh密钥配置正确且git能通过SSH克隆仓库；必须在composer.json中声明vcs类型仓库，URL与远程一致，包名大小写敏感，分支存在；启用2FA后推荐用SSH，否则需app Password配合httpS。
配置SSH密钥并确保能正常克隆仓库
Composer拉取私有Bitbucket仓库的前提是本地Git能通过SSH访问该仓库。如果git clone git@bitbucket.org:username/repo.git失败，Composer一定失败。
常见错误现象：Failed to download username/repo from source: Failed to execute git clone --mirror 'git@bitbucket.org:username/repo.git' '/path/to/cache'，本质是SSH认证未通过。
- 确认已生成SSH密钥（如
~/.ssh/id_rsa），且公钥已添加到Bitbucket账户的SSH keys设置中 - 运行
ssh -T git@bitbucket.org验证连通性，成功应返回logged in as xxx - 确保
~/.ssh/config中为Bitbucket配置了正确的Host别名（如有需要），避免因域名解析或端口问题中断
在composer.json中正确声明私有仓库
不能直接用require写"username/repo": "dev-main"就完事——Composer默认只查Packagist，必须显式告诉它“这个包从哪来”。
关键点：仓库类型必须设为vcs，URL必须是Git可识别的SSH或https格式（推荐SSH）；若用HTTPS，需确保凭据已缓存或配置了http-basic认证。
{ "repositories": [ { "type": "vcs", "url": "git@bitbucket.org:username/repo.git" } ], "require": { "username/repo": "dev-main" } }-
url字段值必须与git remote get-url origin输出一致（尤其注意是否含.git后缀） - 包名
username/repo需与仓库composer.json中name字段完全匹配，大小写敏感 - 分支名如
dev-main、dev-develop需存在，且对应Git远程分支（不是标签）
处理Bitbucket 2FA或App Password限制
启用双重验证（2FA）后，Bitbucket禁用账户密码登录Git HTTPS请求，但Composer默认仍可能尝试HTTPS回退，导致认证失败。
解决路径只有两条：坚持用SSH（推荐），或改用App Password + HTTPS URL。
- 若坚持HTTPS，在
repositories.url中写https://user:app_password@bitbucket.org/username/repo.git，其中app_password需在Bitbucket中创建（权限勾选repository:read） - 更安全的做法是全局配置Git凭证助手：
git config --global credential.helper store，然后首次git clone https://...输入App Password，后续Composer会复用 - 检查
composer config -g github-oauth.bitbucket.org——这个配置无效，Bitbucket不支持GitHub OAuth方式
执行安装时的关键注意事项
运行composer install或composer update时，Composer不会自动提示你缺SSH密钥或权限不足，而是静默卡在“Cloning into bare repository…”或报错退出。
- 加
-vvv参数看完整日志：composer update -vvv，重点找Executing command (CWD): git clone --mirror ...那一行的退出码 - 如果项目已存在
vendor/，先删掉再重装，避免缓存干扰 - CI/CD环境（如GitHub Actions、gitlab CI）需额外注入SSH私钥或App Password，并确保
known_hosts已预置Bitbucket指纹，否则首次连接会挂起
最常被忽略的是：开发者本地能git clone成功，但CI里没配SSH agent或没运行ssh-add，结果部署时突然失败。这类问题不暴露在本地，得靠CI日志逐行盯命令执行过程。