bitbucket-oauth配置是Composer访问Bitbucket私有仓库的唯一有效方式；必须通过composer config命令写入全局或项目级配置，配合具备repo:read权限的OAuth token，并在repositories中显式声明vcs类型。
composer config bitbucket-oauth 是唯一有效方式
Composer 访问 Bitbucket 私有仓库时，bitbucket-oauth 配置是绕不开的认证入口——它不是可选插件，而是官方强制要求的凭证通道。不配这个，composer install 或 composer update 一定会卡在 Could not fetch https://api.bitbucket.org/2.0/repositories/xxx/yyy 或直接报 403 Forbidden。
实操上必须用命令行写入全局或项目级配置，不能手改 auth.json 文件（容易格式错、权限错、路径错）：
-
composer config -g bitbucket-oauth.bitbucket.org <your-token></your-token>（全局，推荐） -
composer config bitbucket-oauth.bitbucket.org <your-token></your-token>（仅当前项目，auth.json会生成在项目根目录）
注意：bitbucket.org 是固定域名，不能写成 www.bitbucket.org 或 api.bitbucket.org，否则无效。
Bitbucket OAuth token 必须带 repo:read 权限
Token 权限不足是 90% 的“配置了但还是 403”的根源。Bitbucket 的 OAuth token 和 Personal Access Token 不同，必须手动勾选权限——默认新建的 token 几乎全是空权限。
创建路径：Bitbucket 设置 → App passwords（不是 OAuth consumers）→ 点击 Create app password → 在权限列表里至少勾选：
-
Repositories: Read（必需） -
Account: Read（部分私有组织仓库需要）
别选 Workspace membership 或 Pull requests，它们和 Composer 拉代码无关；也别用旧版 OAuth consumers，它已弃用且不兼容 Composer 2+。
私有仓库 require 写法必须用 ssh 或 https + vcs 类型声明
即使配好了 bitbucket-oauth，如果 composer.json 里写的是普通 https URL，Composer 仍会跳过认证走匿名请求。
正确写法只有两种：
- 用 SSH（推荐）：
"vendor/package": "dev-main"+"repositories": [{"type": "vcs", "url": "git@bitbucket.org:vendor/package.git"}] - 用 HTTPS（需显式声明 vcs）：
"repositories": [{"type": "vcs", "url": "https://bitbucket.org/vendor/package.git"}]
错误写法："https://bitbucket.org/vendor/package.git" 直接塞进 require，或漏掉 "type": "vcs" —— 这会导致 Composer 当作包名解析，完全不触发 OAuth 流程。
auth.json 权限和位置错一个就失效
auth.json 是敏感文件，Composer 对它的读取非常严格：路径错、权限宽、JSON 格式多逗号，全都会静默失败（不报错，但 token 就是不用）。
- 全局配置时，文件路径必须是
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows） - 文件权限必须是
600（Linux/macOS），否则 Composer 会忽略它：chmod 600 ~/.composer/auth.json - 内容必须是合法 JSON，顶层是对象，不能有多余逗号，不能有注释
验证是否生效：运行 composer config --global --list | grep bitbucket，能看到输出才算真正写入成功。
复杂点在于：Bitbucket 的 OAuth 机制和 GitHub 完全不同，它不支持 token 放 URL 里（如 https://token@bitbucket.org/...），也不接受 http-basic 配置。所有绕开 bitbucket-oauth 的尝试，最终都会撞墙。
