中文镜像（如阿里云、腾讯云）不校验认证，auth.json对其基本无效；auth.json仅在直连私有仓库（如GitLab、GitHub Packages）时生效，且域名必须与请求Host严格一致。
项目根目录的 auth.json 和中文镜像（如阿里云、腾讯云 Packagist 镜像）通常不需要配合使用，强行配反而容易导致认证失败或静默失效。 因为绝大多数中文镜像不校验认证信息——它们只缓存公开包，不代理私有仓库请求。真正需要 auth.json 的，是直接访问私有 Packagist、GitLab Package Registry 或 GitHub Packages 的场景。
为什么中文镜像下 auth.json 基本不起作用
Composer 在安装包时，会先查 repositories 配置决定从哪拉取。如果你用的是默认配置或显式设置了中文镜像（如 "packagist.org": false + 自定义镜像源），Composer 就不会向原始私有域名发起任何请求，自然也用不上 auth.json 里为 repo.example.com 配的凭证。
常见错误现象：
- 明明在
auth.json里写了"http-basic": {"gitlab.company.com": {...}}，但执行composer install仍报401 Unauthorized - 报错 URL 显示的是
https://mirrors.aliyun.com/...，说明流量根本没走到你的私有域名
关键判断点：composer diagnose 输出里 “Repo:” 行显示的实际源地址，才是 auth.json 要匹配的 host。
auth.json 的域名必须和实际请求 host 完全一致
哪怕只差一个端口、一个子域、一个协议前缀，auth.json 就不会生效。这不是“大概匹配”，而是严格字符串比对。
实操建议：
Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。
- 运行
composer install -v，看最后失败的完整 URL —— 把https://后、第一个/前的部分整个复制下来，作为auth.json中http-basic的 key - 例如报错是
Could not fetch https://packages.internal:8080/v2/xxx，key 必须是"packages.internal:8080"，不是"packages.internal"，也不是"https://packages.internal:8080" - 如果用了反向代理（比如 Nginx 把
https://pkg.myorg.com转发到后端http://10.0.1.5:8080），auth.json里填的仍是"pkg.myorg.com"，因为那是 Composer 发出请求时的 Host 头
项目级 auth.json 的权限与位置陷阱
放在项目根目录看似简单，但三个细节极易被忽略：
- 文件权限必须 ≤600（Linux/macOS），否则 Composer 会拒绝读取；Windows 下虽不校验权限，但若通过 WSL 或 CI 环境运行，仍可能因挂载权限问题失效
- 必须和
composer.json在同一目录，不能放在config/auth.json或vendor/auth.json—— Composer 根本不扫描子目录 -
.gitignore里必须包含auth.json；如果已误提交，仅git rm --cached auth.json不够，还需git commit --amend或 filter-repo 清除历史记录，否则 token 仍在 Git 对象里
更隐蔽的问题：CI/CD 中若用 COMPOSER_AUTH 环境变量注入 JSON 字符串，它会完全覆盖本地 auth.json，此时项目根目录下的文件形同虚设。
什么时候才真需要 auth.json 配合镜像
极少数企业自建镜像服务（非公开的阿里云/腾讯云镜像），同时代理公开包 + 私有包，并要求对私有路径做鉴权。这时才需让镜像域名和 auth.json 的 key 对齐。
但这种架构本身复杂度高，且需镜像服务支持透传认证头。绝大多数团队更稳妥的做法是：
- 公开包走中文镜像（通过
composer config repo.packagist composer https://mirrors.aliyun.com/composer/） - 私有包单独加
repositories条目，类型为composer，URL 指向真实私有仓库地址（如https://repo.mycompany.com） -
auth.json只为这个真实私有域名配置，和镜像配置互不干扰
真正容易出问题的，从来不是怎么写 JSON，而是没看清 Composer 实际发请求的 host 是什么 —— 这个 host 决定了 auth.json 里该填哪一行 key。
