如何将Bitbucket私有仓库配置为Composer的依赖源？（SSH/OAuth）-composer-PHP中文网

如何将Bitbucket私有仓库配置为Composer的依赖源？（SSH/OAuth）

冰火之心

发布： 2025-12-18 11:58:46

原创

285人浏览过

要让 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 环境单独配置。

如何将bitbucket私有仓库配置为composer的依赖源？（ssh/oauth）

要让 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，先确认是否生效：

ProcessOn

免费在线流程图思维导图，专业强大的作图工具，支持多人实时在线协作

925

查看详情

运行 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，不能依赖本地配置