要让 Composer 从 Bitbucket 私有仓库拉取依赖，必须配置 SSH 密钥或 App Password 实现身份认证：SSH 方式需确保本地 Git 可克隆、密钥已添加至 Bitbucket 并在 composer.json 中使用 git@bitbucket.org:username/repo.git 格式；App Password 方式需在 Bitbucket 创建只读密码，通过 composer config -g http-basic.bitbucket.org 用户名 密码 配置全局凭据，并在 composer.json 中使用 HTTPS URL；验证时可用 composer config -g --list、composer diagnose 和 composer install -v 检查，注意 name 字段一致性、URL 大小写及 CI/CD 环境单独配置。
要让 Composer 从 Bitbucket 私有仓库拉取依赖，核心是解决身份认证问题。Bitbucket 不允许匿名访问私有库，所以必须配置 SSH 密钥或 OAuth（App Password），并让 Composer 能正确使用它们。下面分两种主流方式说明，重点讲清关键步骤和容易出错的地方。
用 SSH 方式接入私有仓库
SSH 是最常用、也最稳定的方式，适合团队开发环境。前提是你的本地 Git 已能通过 SSH 克隆该私有仓库（比如 git clone git@bitbucket.org:username/repo.git 能成功）。
- 确保 SSH 密钥已添加到 Bitbucket 账户：生成密钥（如未有）
ssh-keygen -t ed25519 -C "your_email@example.com"，再把~/.ssh/id_ed25519.pub内容粘贴到 Bitbucket → Settings → SSH keys - 在
composer.json中声明仓库类型为vcs，URL 使用 SSH 格式："repositories": [{ "type": "vcs", "url": "git@bitbucket.org:username/private-package.git" }] - Composer 默认会复用系统 SSH 配置，无需额外设置；但若你用了非默认密钥路径或别名，需在
~/.ssh/config中配好 Host 别名，并确保git命令能连通
用 App Password（OAuth 替代方案）方式接入
Bitbucket 已弃用 OAuth 1.0a，现在推荐用「App Password」——本质是带权限的密码，比明文账号密码更安全，且可单独控制权限范围。
- 在 Bitbucket 网页端进入 Settings → App passwords → Create app password，勾选
Repositories: Read（如果只是拉依赖，不需要写权限） - 生成后立即复制保存（仅显示一次），例如得到密码
AtBcD3fGhIjKlMnOpQrStUvWxYz12 - 在终端运行：
composer config -g http-basic.bitbucket.org username AtBcD3fGhIjKlMnOpQrStUvWxYz12
其中username是你的 Bitbucket 用户名（不是邮箱） - 在
composer.json中使用 HTTPS URL："url": "https://bitbucket.org/username/private-package.git"
验证与调试技巧
配置完别急着 composer install，先确认是否生效：
- 运行
composer config -g --list | grep bitbucket查看全局凭据是否存入 - 用
composer diagnose检查网络和配置基本状态 - 加
-v参数执行安装，观察是否出现Cloning...或Downloading...，失败时错误信息通常明确提示是认证失败还是仓库不存在 - 如果提示
Could not fetch+403，大概率是 App Password 权限不足或已失效；如果是Permission denied (publickey)，检查 SSH 密钥是否加载（ssh -T git@bitbucket.org测试）
注意事项与常见坑
这些细节不注意，很容易卡住：
- 私有包的
composer.json必须含合法name字段（格式如vendor/name），且和你在主项目中require的名字完全一致 - Bitbucket 的仓库 URL 区分大小写，
username和repo-name必须和网页地址严格一致 - 如果用 SSH，确保
git命令本身能克隆成功——Composer 底层调用的就是git clone，它失败了 Composer 一定失败 - CI/CD 环境（如 GitHub Actions、Bitbucket Pipelines）需要单独注入 SSH 私钥或 App Password，不能依赖本地配置
基本上就这些。SSH 更省心，适合长期维护；App Password 更灵活，适合自动化场景。选一种配通，后续更新依赖就跟公开包一样自然了。
