auth.json是composer本地凭据凭证箱，仅支持http-basic、github-oauth、gitlab-token三个顶层键；域名必须与请求主机名完全一致，权限需≤600，按项目根目录→$composer_home→composer_auth顺序生效。
auth.json 文件只记录认证凭据，不存任何项目逻辑或依赖关系；它本质是 Composer 的本地凭据凭证箱，内容必须严格按字段名和域名匹配才生效。
auth.json 里能写哪些字段
合法顶层键只有三个：http-basic、github-oauth、gitlab-token。其他字段（比如 bearer、auth、tokens）会被 Composer 完全忽略。
-
http-basic用于私有 Packagist、Nexus、Artifactory 等支持 HTTP Basic Auth 的仓库，结构为{"username": "xxx", "password": "yyy"}—— 注意：很多私仓要求把 token 填进username，password留空 -
github-oauth仅对 GitHub 私有 repo 生效，值必须是带read:packages权限的 Personal Access Token（不是密码，也不是 OAuth App token） -
gitlab-token对应 GitLab Package Registry，值是glpat-xxx格式的 Personal Access Token，需含read_api
域名填错就等于没配
报错里出现的 URL 主机名，就是 http-basic 对象里的 key —— 必须一字不差。
- 如果报错是
Could not fetch https://api.internal.company:8080/v2/packages.json，key 就得是"api.internal.company:8080"（端口不能省） - 如果仓库 URL 是
https://gitlab.example.org/api/v4/groups/mygroup/-/packages/composer，key 只取"gitlab.example.org"（协议、路径、查询参数全去掉） -
www.repo.com和repo.com是两个不同 host，不能混用 - 反向代理场景下，填的是请求发出时实际发往的 Host 头，不是你浏览器地址栏里输的域名
为什么 config --auth 写进 composer.json 是危险操作
composer config --auth 会把凭据直接写进项目 composer.json 的 config 字段，等同于把 token 提交到 Git —— 这是高危行为。
- 正确做法是用
composer config http-basic.packages.example.com user token（项目级）或composer config --global http-basic.packages.example.com user token（全局级），命令自动创建auth.json并设好权限（Linux/macOS 下默认600） - 项目根目录的
auth.json必须加进.gitignore；若已误提交，要git rm --cached auth.json并重置历史 - CI/CD 中绝不要硬编码
auth.json，应通过COMPOSER_AUTH环境变量注入 JSON 字符串
权限与优先级常被忽略的细节
文件权限不对、位置放错、环境变量覆盖，都会导致配置静默失效。
- Linux/macOS 下，
auth.json权限超过600（比如644），Composer 会直接跳过读取，不报错也不提示 - 查找顺序是：项目根目录
auth.json→$COMPOSER_HOME/auth.json→COMPOSER_AUTH环境变量；只要前面一个命中，后面全不读 - Windows 默认路径是
%APPDATA%\Composer\auth.json，不是%USERPROFILE%\.composer\auth.json，手动生成容易放错 - 运行
composer config --global --list | grep http-basic可快速验证全局配置是否被识别
真正卡住人的往往不是“怎么写”，而是“写在哪”“写成啥样”“被谁覆盖了”——尤其在 Docker 或 CI 环境中，$COMPOSER_HOME 路径、用户身份、环境变量加载时机，三者一错，认证就掉链子。
