Composer怎么配置Bitbucket仓库 链接Bitbucket私有源【教程】

composer 无法通过 httpS 克隆 Bitbucket 私有仓库，因不支持交互式认证；应改用 ssh 协议（需配置密钥）或 Bitbucket app Password（仅 Cloud，需 URL 重写与凭据缓存）。

Composer 无法直接通过 https 克隆 Bitbucket 私有仓库，必须用 SSH 或配置 OAuth 令牌；HTTPS 方式默认会卡在认证环节，因为 Composer 不弹出密码输入框。

为什么 composer require 拉不下来 Bitbucket 私有包？

Bitbucket 私有仓库默认禁用匿名克隆，而 Composer 的 git 驱动在 HTTPS 协议下不会触发交互式登录（比如输账号密码），导致报错：Failed to execute git clone --mirror 'https://bitbucket.org/xxx/yyy.git' ... fatal: could not read Username for 'https://bitbucket.org': No such device or address。这不是 Composer 配置问题，是协议层限制。

正确做法：改用 SSH 协议 + 全局 Git 配置

这是最稳定、无需每次输密的方案，前提是你的机器已配好 Bitbucket SSH key 并添加到账户中：

• 确认本地 Git 能通过 SSH 访问：git ls-remote git@bitbucket.org:your-team/your-repo.git 应返回 ref 列表
• 在 composer.json 中声明仓库时，url 字段必须写成 SSH 格式："url": "git@bitbucket.org:your-team/your-repo.git"，不能带 https://
• 确保 type 是 vcs，例如："type": "vcs"
• 如果该仓库是作为依赖被 require，且未发布到 Packagist，需在根项目 composer.json 的 repositories 里显式注册

替代方案：用 Bitbucket App Password + HTTPS（仅限 Bitbucket Cloud）

若无法用 SSH（如 CI 环境无密钥管理），可用 App Password 替代账号密码，但必须重写 Git URL 并配置 Git 凭据助手：

• 在 Bitbucket 设置里创建一个 App Password（权限勾选 repository:read）
• 把仓库 URL 改成：https://@bitbucket.org/your-team/your-repo.git
• 运行 git config --global credential.helper store，然后手动执行一次 git ls-remote https://.../your-repo.git 触发凭据缓存
• Composer 会复用 Git 的凭据缓存，后续操作不再报错
• 注意：App Password 不能含特殊字符（如 /、@），否则 URL 解析失败；建议用 Base64 编码或换用 SSH

常见陷阱和验证点

很多问题其实出在细节上：

• composer.json 里的 name 字段必须和 Bitbucket 仓库路径严格一致（如 your-team/your-repo），否则 Composer 找不到匹配包
• 私有仓库的 composer.json 必须有合法 version（如 "dev-main" 或带 v 前缀的 tag），否则 Composer 无法解析稳定性
• 运行 composer install -vvv 查看详细日志，重点找 Executing command (CWD) 行，确认实际执行的是 SSH 还是 HTTPS 命令
• Bitbucket Server（自建版）不支持 App Password，只能走 SSH 或 HTTP Basic + 服务端反向代理透传认证头

SSH 是首选，但得确保部署环境能访问你的密钥；App Password 看似简单，但 URL 编码和凭据缓存时机很容易漏掉。真正在生产环境跑通，往往卡在 Git 层而非 Composer 层。