Bitbucket私有库Composer安装失败的根本原因是未配置OAuth令牌导致401错误，必须通过auth.json配置App Password并设置vcs仓库地址与包名一致。
Bitbucket 私有库安装失败：Composer 报 401 Unauthorized 或 Could not fetch
根本原因是 Composer 默认不携带 Bitbucket OAuth 令牌，而私有仓库需要身份认证。直接在 composer.json 里写 https://bitbucket.org/xxx/yyy.git 会触发匿名请求，必然被拒绝。
解决路径只有一条：让 Composer 在访问 Bitbucket 时自动带上有效令牌。这不是靠改 repositories 配置能绕过的，必须配置全局或项目级的 auth.json。
- Bitbucket 不支持 HTTP Basic Auth（即用户名+密码），仅接受
app password或OAuth consumer（推荐前者） - 令牌必须拥有
repository:read权限（如果是私有库，还需repository:write如果要 push） -
auth.json文件位置优先级：项目根目录auth.json>COMPOSER_HOME/auth.json（通常是~/.composer/auth.json）
生成 Bitbucket App Password 并写入 auth.json
App Password 是最轻量、最可控的身份凭证方式，比 OAuth consumer 更易维护，也无需回调地址等配置。
- 登录 Bitbucket → 左下角头像 → Personal settings → App passwords → Create app password
- 命名如
composer-read-private-repos，勾选权限：Repositories: Read（必须），Account: Read（可选，用于获取用户信息） - 生成后立即复制该密码（仅显示一次！）
- 在项目根目录或
~/.composer/下创建auth.json，内容如下：
{
"bitbucket.org": {
"consumer_key": "",
"consumer_secret": "",
"oauth_token": "",
"oauth_token_secret": "",
"password": "APP_PASSWORD_HERE"
}
}
注意：password 字段值就是刚复制的 App Password；其他 OAuth 字段留空即可 —— Composer 会自动识别并使用 password 模式进行 Basic Auth（它把 username 当作你的 Bitbucket 用户名，password 当作 App Password）。
composer.json 中正确声明私有仓库
不能只靠 auth.json 就完事。Composer 还得知道这个包从哪来、怎么解析。关键点在于：用 vcs 类型 + 完整 HTTPS Git 地址，并确保包名与仓库实际命名一致。
- Bitbucket 的私有仓库 URL 格式是
https://bitbucket.org/{workspace}/{repo-slug}.git，不是 SSH 或网页链接 -
name字段必须匹配目标包的name（即vendor/name），否则 Composer 找不到匹配项 - 不要加
dist或source配置 —— VCS 类型下 Composer 自动处理
{
"repositories": [
{
"type": "vcs",
"url": "https://bitbucket.org/myorg/my-private-package.git"
}
],
"require": {
"myorg/my-private-package": "^1.0"
}
}
运行 composer install 或 composer update 时，Composer 会读取 auth.json，对 bitbucket.org 域名的所有请求自动附加 Authorization: Basic ... 头，完成认证。
调试与常见陷阱
如果仍报错，别急着重试，先确认三件事：
- 运行
composer config --global --list | grep bitbucket看是否意外设置了冲突的 global auth 配置 - 检查
auth.json是否被 Git 忽略（应加入.gitignore！），但确保它真实存在于 Composer 查找路径中 - 错误信息含
Failed to clone https://bitbucket.org/...？说明 Composer 没读到auth.json，或令牌权限不足；含Could not parse version constraint？大概率是composer.json里name和 require 的不一致 - Bitbucket workspace 名称大小写敏感，
MyOrg≠myorg，URL 和name必须完全一致
App Password 一旦失效（比如被删除或过期），Composer 不会提示“令牌过期”，只会反复报 401 —— 这时候最容易卡住。建议把 App Password 的创建时间、用途记在密码管理器里，而不是靠记忆。
