auth.json 必须放在项目根目录、用户主目录（~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）或 COMPOSER_HOME 指定路径，Composer 按此顺序查找且找到即停；位置错误、权限过高（Linux/macOS 需 ≤600）、域名不匹配或未清缓存是常见失效原因。
auth.json 放哪儿才被 Composer 读到
Composer 查找 auth.json 有固定顺序：项目根目录（./auth.json）→ 用户主目录（~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）→ COMPOSER_HOME 指定路径。找到即停，不会合并多个文件。
常见失效原因不是内容写错，而是位置不对：
- CI 环境里误以为把
auth.json放进项目根目录就能全局生效——其实它只影响当前项目，而 CI 往往以不同用户身份运行（比如www-data），权限不匹配就静默忽略 - Linux/macOS 下用户级
auth.json权限必须 ≤600，否则 Composer 直接跳过，不报错也不提示 - Windows 上路径容易写成
C:\Users\Name\.composer\auth.json，但实际应是%APPDATA%\Composer\auth.json（通常是C:\Users\Name\AppData\Roaming\Composer\auth.json）
github-oauth 和 http-basic 字段不能混用或拼错
auth.json 的顶层键只有两个合法值：http-basic 和 github-oauth（gitlab-token 是额外支持字段，非标准但广泛兼容）。其他字段名如 github_oauth、gitlab-oauth、token 全部被忽略，且 Composer 不报错。
关键细节：
-
github-oauth的 key 必须是"github.com"，哪怕你用 GitHub Enterprise，也得填对应实例域名（如"git.example.com"），并配config中的github-url -
http-basic的域名必须和composer.json里repositories.url的 host 完全一致：带端口要带端口（"repo.example.com:8443"），带www要带www（"www.repo.example.com"），HTTPS 协议不影响匹配 - 私有 Nexus/Artifactory 常要求把 token 填在
username字段、password留空——这不是 bug，是它们对 HTTP Basic 的实现方式
用 composer config 命令写入比手写更安全
手动编辑 auth.json 容易出 JSON 格式错误，且密码会留在 shell 历史里。用 composer config 可自动处理转义、路径定位和权限设置（如 Linux 下设为 600）。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
常用命令：
- 项目级 HTTP Basic：
composer config http-basic.packagist.example.com deploy-token abc123xyz - 全局 GitHub OAuth：
composer config --global github-oauth.github.com ghp_xxx - 全局 GitLab Token：
composer config --global gitlab-token.gitlab.example.com glpat-xxx
注意：composer config 不支持交互式录入 github-oauth，所以全局配置 GitHub token 时仍需手动补全 auth.json 文件结构。
CI 环境别生成 auth.json 文件
CI 流水线中硬生成 auth.json 文件是高危操作，一旦日志泄露或缓存残留，token 就暴露了。正确做法是通过环境变量注入：
- GitHub Actions：
COMPOSER_AUTH='{ "github-oauth": { "github.com": "${{ secrets.GITHUB_TOKEN }}" } }' - GitLab CI：
COMPOSER_AUTH='{ "gitlab-token": { "gitlab.example.com": "$GITLAB_TOKEN" } }'
环境变量优先级高于所有 auth.json 文件，且生命周期仅限当前 job。另外，务必清除 Composer 缓存：composer clear-cache，否则旧的 401 响应可能被缓存，掩盖新配置是否生效。
最容易被忽略的是域名拼写一致性与缓存干扰——改完配置却没清缓存，或者 URL 写成 https://gitlab.example.com/group/repo.git，但 auth.json 里写的是 "gitlab.example.com"（少了个 /group/repo.git？不，host 部分不需要路径，但必须和 URL 的 host 完全相同，包括大小写和端口）。
