必须执行 composer config bitbucket-oauth.bitbucket.org，否则私有库拉取会因认证失败返回403或卡在API请求；Composer 2+仅支持该配置项，严格校验域名、强制App Password格式并自动写入权限为600的auth.json。
必须执行 composer config bitbucket-oauth.bitbucket.org，否则所有私有库拉取都会卡在 Could not fetch https://api.bitbucket.org/2.0/repositories/ 或直接返回 403 —— 这不是可选项，是 Composer 2+ 唯一认的认证入口。
为什么 bitbucket-oauth.bitbucket.org 是强制配置项
Composer 2+ 彻底移除了对 http-basic.bitbucket.org 的支持，也废弃了 OAuth consumer。现在只解析 bitbucket-oauth.bitbucket.org 这一配置项，且内部做了三件事：
- 校验域名是否为严格
bitbucket.org（不接受www.bitbucket.org、api.bitbucket.org或带协议前缀） - 强制要求 App Password 格式（不是账号密码，也不是 OAuth token）
- 自动写入
auth.json并设权限为600
手写 auth.json 容易字段错位或权限不对，导致静默跳过认证。执行命令时域名必须写成 bitbucket.org，不能加 https:// 或路径；App Password 必须由你本人的 Bitbucket 账号生成，且至少勾选 Repositories: Read。
composer.json 中仓库地址怎么写才有效
即使 auth.json 配对了，只要 composer.json 里漏掉任意一条，Composer 就当普通公开包处理，完全不触发认证流程：
立即学习“PHP免费学习笔记（深入）”；
-
"type": "vcs"必须显式写出，不能留空、不能写成"package"或"git" -
"url"必须是完整 Git 克隆地址，以.git结尾，例如"https://bitbucket.org/vendor/package.git"；填网页地址或少.git后缀会直接 404 - 包名（如
"vendor/package"）必须和私有仓库中composer.json的name字段完全一致，包括大小写
错误示例："url": "https://bitbucket.org/vendor/package"（缺 .git）、"type": "package"、或直接在 require 里写 URL（Composer 不解析）。
拉取失败时最常被忽略的三个检查点
遇到 403 或超时卡住，别急着重试，先确认这三项：
- 运行
composer config --list | grep bitbucket，确保输出中包含bitbucket-oauth.bitbucket.org且值非空 - 检查
auth.json文件权限：执行ls -l auth.json，必须是-rw-------（即600），否则 Composer 会跳过加载 - 用
git clone https://bitbucket.org/vendor/package.git手动测试——如果这个都失败，说明 App Password 权限不足或已失效，和 Composer 无关
Bitbucket 的认证逻辑很“专一”：它只认 bitbucket-oauth.bitbucket.org 这个键，其他任何变体（比如加 https://、换域名、混用 http-basic）都会被彻底无视。哪怕你本地 git 配置了凭据管理器，Composer 也完全不走那条路。
