auth.json 必须放在项目根目录、COMPOSER_HOME 或系统级配置目录，且仅支持 http-basic 和 github-oauth 两类认证；结构需为顶层 JSON 对象，域名作 key，密码明文，不可放 vendor/ 或命名 auth.json.dist；推荐用 composer config 命令生成以避免格式与安全问题。
auth.json 文件放在哪里才有效
Composer 只会在特定路径下自动读取 auth.json，顺序是：当前项目根目录 → COMPOSER_HOME 目录（通常是 ~/.composer/ 或 %APPDATA%\Composer\）→ 系统级配置目录。项目级的 auth.json 必须和 composer.json 在同一层，且不能被 .gitignore 误删（私有包认证信息通常不该提交，但开发时放本地是常见做法）。
常见错误：把 auth.json 放在 vendor/ 下、或命名为 auth.json.dist 却没启用 config.platform.auth 机制——这些位置 Composer 完全不识别。
auth.json 的正确结构和字段写法
它是个纯 JSON 文件，顶层必须是对象，只支持 http-basic 和 github-oauth 两类认证方式。私有 Packagist 或 GitLab 私仓用 http-basic；GitHub 私有仓库用 github-oauth。
关键点：
-
http-basic的 key 是仓库域名（如"packagist.example.com"），不是协议或路径 - 用户名密码必须是明文字符串，不能是环境变量引用（
${ENV_VAR}不生效） - GitHub token 要填在
github-oauth下，key 固定为"github.com"，哪怕你用的是 GitHub Enterprise，也得写成"github.com"并配gitHubUrl到 config
示例（私有 Packagist）：
{
"http-basic": {
"packagist.example.com": {
"username": "deploy-token",
"password": "abc123xyz"
}
}
}
用 composer config 命令生成 auth.json 更安全
手动写 JSON 容易格式出错，而且密码明文暴露在命令行历史里。用 composer config 命令可避免这两点：
- 项目级写入：
composer config http-basic.packagist.example.com deploy-token abc123xyz - 全局写入（写入
COMPOSER_HOME/auth.json）：composer config --global http-basic.packagist.example.com deploy-token abc123xyz
执行后 Composer 自动创建/更新 auth.json，并确保 JSON 格式合法。注意：该命令不支持 GitHub OAuth token 的交互式录入，必须手动编辑 auth.json 添加 github-oauth 段。
为什么有时 auth.json 不生效？排查这三点
最常踩的坑不是文件写错，而是环境或权限干扰：
- 运行
composer install的用户和写auth.json的用户不一致（比如 CI 中用www-data用户跑，但auth.json是 root 写的，权限 600 就读不到） - 用了
--no-auth参数，或设置了环境变量COMPOSER_NO_INTERACTION=1且未预置凭证 - 私有仓库 URL 在
composer.json的repositories里写成了https://user:pass@packagist.example.com—— 这种内联认证会覆盖auth.json，且 Composer 8+ 已警告弃用
验证是否加载成功，加 -v 参数运行 composer update，看到类似 Reading authentication from /home/user/.composer/auth.json 才算到位。
复杂点在于：不同 Composer 版本对 auth.json 的解析细节有差异，尤其是 v2.2+ 加强了域名匹配逻辑；另外，某些企业镜像服务要求额外 header（如 X-Registry-Auth），这时光靠 auth.json 不够，得配合 composer config extra.registry-auth 或自定义 plugin。
