必须执行composer config bitbucket-oauth.bitbucket.org，这是Composer 2+唯一有效的Bitbucket认证方式；它严格校验bitbucket.org域名、强制使用个人账号生成的含Repositories: Read权限的App Password，并自动写入权限为600的auth.json。
必须执行 composer config bitbucket-oauth.bitbucket.org，否则所有私有库拉取都会卡在 Could not fetch https://api.bitbucket.org/2.0/repositories/ 或直接 403 —— 这不是可选项，是 Composer 2+ 唯一认的认证入口。
为什么 composer config 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 就当普通公开包处理，完全不触发认证流程：
-
"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 不解析）。
App Password 怎么生成才真正可用
Bitbucket 的 App Password 页面只显示一次明文，关掉就再也看不到——绝大多数“配了没用”的问题，其实只是复制不全、用了已撤销的 token，或权限没勾对：
- 入口路径：右上头像 → Personal settings → App passwords → Create app password
- 名称随意（如
composer-read-private），但权限至少勾选Repositories: Read；Account: Read可选，但部分旧版 Composer 会校验它 - 不能用团队账号生成 —— 必须用实际拥有仓库读权限的个人账号
- 如果你的账号启用了 SSO，App Password 将被禁用，必须先关闭 SSO 或联系管理员授权
生成后立刻复制保存，页面刷新就再也看不到了；如果提示 This app password has been revoked，说明你删过或重生成了，得换新的。
常见报错与验证方式
典型错误现象：Could not fetch https://api.bitbucket.org/2.0/repositories/xxx/yyy、enter your bitbucket.org credentials、或直接报 401 Unauthorized / 403 Forbidden：
- 验证是否写入成功：运行
composer config --auth --list | grep bitbucket，能看到类似bitbucket-oauth.bitbucket.org的条目；若为空或显示***，说明没写入或值为空 - 运行
composer clear-cache，否则 Composer 可能复用旧的未授权请求头 - CI 环境（如 GitHub Actions）中，
composer config写的是本地用户目录，需显式指定--global，或用环境变量COMPOSER_AUTH注入 JSON 字符串 - Bitbucket Server（自建版）不支持
bitbucket-oauth，得走http-basic+ Basic Auth，别混用
最常踩的坑不是密码错，而是认证域没对上 —— 域名写成 www.bitbucket.org 或 api.bitbucket.org 会导致配置静默失效，不报错也不起作用。
