Composer 2+ 必须使用 composer config bitbucket-oauth bitbucket.org <app-password> 配置认证，域名严格为 bitbucket.org（不可加 www 或 api），URL 需以 .git 结尾且 repositories 中 type 必为 "vcs"，包名与分支名须完全匹配远程仓库，App Password 需个人账号生成并勾选 Repositories: Read 权限。
必须执行 composer config bitbucket-oauth bitbucket.org
Composer 2+ 完全弃用 http-basic.bitbucket.org 和 OAuth consumer，bitbucket-oauth 是唯一生效的认证入口。填错域名（比如 www.bitbucket.org 或 api.bitbucket.org）会导致配置静默失效，不报错也不起作用。
这个命令会自动把 App Password 写进 auth.json（项目级优先写入根目录，无则 fallback 到 ~/.composer/auth.json），格式校验、文件锁、权限设置都由 Composer 自己处理，比手写安全得多。
验证是否成功：运行 composer config --auth --list，能看到类似 bitbucket-oauth.bitbucket.org 的条目；若为空或显示 ***（被掩码），说明没写入或值为空。
repositories 里必须写 "type": "vcs" 和带 .git 后缀的 HTTPS URL
只在 require 里写包名，或者 repositories 中漏掉 type 字段、写成 "type": "package"，Composer 就当普通 Packagist 包处理，完全不触发 Bitbucket 认证流程。
正确写法示例：
{
"repositories": [
{
"type": "vcs",
"url": "https://bitbucket.org/your-workspace/your-private-package.git"
}
],
"require": {
"your-workspace/your-private-package": "dev-main"
}
}
关键点：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- URL 必须以
.git结尾，不能是网页地址（如https://bitbucket.org/.../...） - 包名（
your-workspace/your-private-package）必须和仓库内composer.json的name字段严格一致（含大小写） - 分支名（如
dev-main）必须真实存在于远程仓库，且是 Git 分支，不是标签或本地分支
App Password 必须用个人账号生成，且勾选 Repositories: Read
Bitbucket Cloud 不再接受账号密码直连，必须用 App Password——它本质是 OAuth2 风格凭证，但 Composer 只认用户名 + 密码组合形式。
生成路径：右上头像 → Personal settings → App passwords → Create app password。
务必注意：
- 权限至少勾选
Repositories: Read；Account: Read建议也勾，部分 Composer 版本会校验 - 必须用拥有目标仓库读权限的个人账号生成，不能用团队/组织账号——Composer 按 token 绑定的用户身份校验权限
- 如果账号启用了 SSO，App Password 会被禁用，需先关闭 SSO 或联系管理员授权
- 生成后页面只显示一次，关闭即不可恢复；复制后立刻存到安全地方
CI 环境或缓存问题常导致“配了却失败”
本地能装，CI 报 Could not fetch https://api.bitbucket.org/2.0/repositories/...，大概率是以下三者之一：
- CI 中未显式执行
composer config --global bitbucket-oauth bitbucket.org <token>，或没通过COMPOSER_AUTH环境变量注入 JSON 字符串 - 本地改完配置后没清缓存，运行
composer clear-cache再试 - 用了 Bitbucket Server（自建版），
bitbucket-oauth不支持，得换http-basic配置
调试时加 -vvv 参数：composer install -vvv，看日志里是否出现 Authorization: Basic 头；没有，说明认证根本没触发，回头检查 repositories.type 和 URL 格式。
最容易被忽略的是：私有包自己的 composer.json 里没设 branch-alias，而主项目又没调 --prefer-stable 或放宽 minimum-stability，结果 Composer 直接跳过安装——这跟认证无关，但错误现象一模一样。
