如何将私有的Bitbucket仓库配置为Composer的包源？

要让 Composer 从私有 Bitbucket 仓库加载包，需配置 App Password（HTTPS）或 SSH 密钥，并在 composer.json 的 repositories 中声明 vcs 类型及对应 URL；包名与分支名须与仓库一致。

要让 Composer 从私有的 Bitbucket 仓库加载包，核心是让 Composer 能够认证并拉取代码。Bitbucket 不支持直接用密码认证（尤其在启用双重验证后），必须使用 App Password 或 SSH 密钥 方式，并在 composer.json 中正确声明仓库类型和地址。

配置 Bitbucket App Password（推荐 HTTPS 方式）

Bitbucket Cloud 要求使用 App Password 替代账户密码进行 Git 操作：

• 登录 Bitbucket → 右上角头像 → Personal settings → App passwords
• 点击 Create app password，勾选 Repositories: Read（如果需要推送则加 Write）
• 生成后复制该密码（仅显示一次，务必保存）
• 在本地运行：git config --global credential.helper store，然后执行一次 git clone https://@bitbucket.org//.git，按提示输入用户名和刚生成的 App Password，Git 会缓存凭证

在 composer.json 中声明私有仓库

Composer 默认不扫描私有仓库，需显式添加 repositories 配置：

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://bitbucket.org/your-username/your-private-package"
    }
  ],
  "require": {
    "your-username/your-private-package": "dev-main"
  }
}

注意：url 必须是 HTTPS 地址（如上），且包名（your-username/your-private-package）需与仓库的 composer.json 中 "name" 字段完全一致；分支名（如 dev-main）要对应实际存在的 Git 分支或标签。

Upscalepics

在线图片放大工具

下载

使用 SSH 方式（适合团队 CI/CD 或免交互场景）

若偏好 SSH，确保：

• 本地已生成 SSH 密钥（ssh-keygen -t ed25519 -C "you@example.com"），并将公钥添加到 Bitbucket 的 Personal settings → SSH keys
• 测试连接：ssh -T git@bitbucket.org，看到 authenticated via a deploy key 或类似提示即成功
• 在 composer.json 中使用 SSH URL："url": "git@bitbucket.org:your-username/your-private-package.git"
• Composer 会自动调用系统 SSH 客户端，无需额外凭证配置

验证与常见问题

运行 composer update your-username/your-private-package 观察输出：

• 若提示 Failed to download... 或 403 Forbidden：检查 App Password 权限、URL 是否拼写错误、是否误用了账户密码
• 若报 Could not fetch... + Permission denied (publickey)：SSH 密钥未正确加载或未添加到 Bitbucket
• 可临时启用调试：composer update -vvv 查看详细网络请求和认证过程