auth.json 必须存于三个指定路径之一：项目根目录（./auth.json）、COMPOSER_HOME 目录下（如 ~/.composer/auth.json）或系统级配置目录，按顺序查找且不合并；key 必须精确匹配仓库 host（不含协议/路径），推荐用 composer config 命令写入并设 .gitignore；CI/CD 中应使用 COMPOSER_AUTH 环境变量传递认证信息。
Composer 认证信息必须存进 auth.json，不能写在 composer.json 里，否则会泄露密码或令牌。
auth.json 文件该放哪儿？路径和优先级要搞清
Composer 只在三个位置找 auth.json，按顺序读取，**先找到就停，不会合并**：
- 当前项目根目录（
./auth.json）→ 仅对本项目生效 -
COMPOSER_HOME目录下（Linux/macOS 通常是~/.composer/auth.json或~/.config/composer/auth.json；Windows 是%APPDATA%\Composer\auth.json）→ 全局生效 - 系统级配置目录（极少用，一般不用管）
常见错误是把文件扔错地方：比如在项目里建了 ./composer/auth.json，但 Composer 只认 ./auth.json；或者改了全局路径却没确认 COMPOSER_HOME 实际指向哪——可用 composer config --global --list | grep config-home 查。
http-basic 的 key 必须精确匹配仓库域名
填错 key 是“Authentication failed”最常见原因。key 不是完整 URL，也不是组织名，而是 仓库地址的 host 部分，不含协议、端口（除非显式指定）、路径：
- 仓库 URL 是
https://packages.myorg.com→ key 是"packages.myorg.com" - 仓库 URL 是
https://repo.internal:8080/api/v1→ key 是"repo.internal:8080"（带端口） - 仓库 URL 是
https://gitlab.company.com/group/pkg→ key 是"gitlab.company.com" - 填
"myorg.com"、"https://packages.myorg.com"或"packages.myorg.com/api"都无效
如果私有源用了自签名证书或反向代理，还要确保域名解析和 TLS 证书 Subject Alt Name（SAN）也匹配这个 key。
用命令行写入比手写更安全可靠
手动编辑 auth.json 容易格式出错（比如多逗号、少引号），也难控制权限。推荐一律用 composer config 命令：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 项目级（只影响当前项目）：
composer config http-basic.packages.example.com alice topsecret123 - 全局级（所有项目都用）：
composer config --global http-basic.packages.example.com alice topsecret123 - GitLab 个人访问令牌（推荐）：
composer config --global gitlab-token.gitlab.com glpat-xxxxxx - GitHub OAuth Token：
composer config --global github-oauth.github.com xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
执行后 Composer 自动创建文件、写入 JSON、设好权限（Linux/macOS 下默认 600）。你只要确认它没被 git add 进仓库就行——务必加进 .gitignore。
CI/CD 环境别写文件，用 COMPOSER_AUTH 环境变量
在 GitHub Actions、GitLab CI 等环境里，硬生成 auth.json 文件风险高（可能残留、日志泄露）。应该用 COMPOSER_AUTH 环境变量传入 JSON 字符串：
{"http-basic": {"packages.example.com": {"username": "alice", "password": "topsecret123"}}}
例如 GitHub Actions 中：
- 把令牌存为 Secret（如
PRIVATE_REPO_TOKEN） - 在 job step 里用
env:注入：COMPOSER_AUTH: '{ "http-basic": { "packages.example.com": { "username": "alice", "password": "${{ secrets.PRIVATE_REPO_TOKEN }}" } } }'
注意：JSON 字符串必须是单行、双引号、转义正确；COMPOSER_AUTH 优先级高于磁盘上的 auth.json，且只在当前进程有效。
最容易被忽略的是域名匹配精度和权限控制——哪怕 token 正确，host 写错一个字符，或 auth.json 被误提交到 Git，整个流程就会静默失败或暴露凭证。
