Composer 支持拉取 Bitbucket 私有仓库，但需显式配置 repositories 为 vcs 类型、URL 以 .git 结尾、通过 auth.json 配置 App Password 认证，并在私有仓库中声明 name 和 version，否则会报 403 或找不到仓库。
Composer 能拉取 Bitbucket 私有仓库，但默认不支持，必须显式配置 composer.json 中的 repositories 并启用认证 —— 否则会报 Could not fetch https://api.bitbucket.org/... 403 或 Repository not found。
Bitbucket 私有仓库必须用 vcs 类型声明
不能用 package 或省略类型，否则 Composer 不会尝试 Git 克隆。Bitbucket 的 HTTPS 地址（如 https://bitbucket.org/username/repo.git）需明确标记为 vcs，且协议必须是 https（SSH 方式需额外配置 SSH agent，不推荐）。
常见错误：直接写 "url": "https://bitbucket.org/xxx/yyy" 却漏掉 "type": "vcs"，导致 Composer 完全忽略该仓库。
-
type字段值只能是vcs（小写），不是git或bitbucket - URL 必须以
.git结尾，否则 Composer 无法识别为 Git 仓库 - 若仓库启用了 Two-Step Authentication，Token 必须带
account:read和repository:read权限
认证要用 auth.json + App Password（不是账号密码）
Bitbucket 已停用账号密码登录 API，必须用「App Password」。该密码需在 Bitbucket 设置页生成，并绑定到具体权限。Composer 认证信息不能硬编码在 composer.json 中，必须通过 auth.json 管理。
项目根目录下创建 auth.json（注意：不要提交到 Git）：
{
"bitbucket.org": {
"consumer-key": "your-app-password-here"
}
}
⚠️ 注意：consumer-key 是旧字段名，Bitbucket 实际只认 http-basic 形式，所以正确写法是：
{
"bitbucket.org": {
"http-basic": {
"bitbucket.org": {
"username": "your-bitbucket-username",
"password": "your-app-password"
}
}
}
}
composer require 时要指定完整包名和版本约束
Bitbucket 仓库不会自动注册到 Packagist，必须手动声明 name（格式为 vendor/package）和 version（或使用 dev- 分支别名）。否则 Composer 找不到匹配的包。
例如，你的 composer.json 在私有仓库中长这样：
{
"name": "acme/utils",
"version": "1.0.0",
"autoload": { "psr-4": { "Acme\\": "src/" } }
}
那么在主项目中运行：
composer require acme/utils:1.0.0
同时确保主项目的 composer.json 包含：
{
"repositories": [
{
"type": "vcs",
"url": "https://bitbucket.org/your-username/utils.git"
}
]
}
调试失败时优先检查 composer diagnose 和网络路径
很多问题其实不是配置错，而是网络或权限链路断了。先运行：
composer diagnose
它会提示 auth.json 是否可读、Bitbucket 域名是否被代理拦截、HTTPS 是否能通。如果输出 HTTP basic authentication is configured for bitbucket.org, but no password was provided，说明 auth.json 格式不对或字段嵌套错了。
另外，Bitbucket 的 API 域名是 api.bitbucket.org，但仓库克隆走的是 bitbucket.org —— 这两个域名都要能访问，且 auth.json 中的 host 必须写成 bitbucket.org，不是 api.bitbucket.org。
