auth.json用于安全存储私有仓库认证凭据，避免泄露；优先级为COMPOSER_AUTH环境变量→项目根目录→COMPOSER_HOME；需注意域名匹配、token权限及Composer版本兼容性。
auth.json 用来存私有仓库的认证凭据
当你用 Composer 安装或更新来自私有 Git 仓库（比如 GitHub Enterprise、GitLab 私有项目、Bitbucket Server）或私有 Packagist 镜像的包时，Composer 需要身份凭证才能拉取代码。这些凭证不能写在 composer.json 里（会提交到版本库，泄露风险高），所以 Composer 设计了 auth.json 文件——它专门负责安全地存用户名/密码、OAuth token、SSH key 路径等认证信息，且默认被 .gitignore 排除。
auth.json 放哪儿？优先级怎么算？
Composer 会按顺序查找 auth.json，找到第一个就停止：
-
COMPOSER_AUTH环境变量（值为 JSON 字符串） - 当前项目根目录下的
auth.json -
COMPOSER_HOME目录下的auth.json（通常是~/.composer/auth.json或~/Library/Application Support/Composer/auth.json或%APPDATA%\Composer\auth.json）
推荐把敏感凭据放在 COMPOSER_HOME 下的全局 auth.json，避免每个项目重复配置；但若团队共用 CI 环境，有时反而要用项目级 auth.json + .gitignore + CI 变量注入方式。
常见 auth.json 结构和易错点
最常出问题的是字段名写错、token 权限不足、或用了不支持的认证方式。以下是典型合法结构：
{
"http-basic": {
"packagist.example.com": {
"username": "api-token",
"password": "ghp_xxx..."
},
"gitlab.company.com": {
"username": "gitlab-ci-token",
"password": ""
}
},
"github-oauth": {
"github.com": "xxx7b9a1f0..."
},
"gitlab-token": {
"gitlab.company.com": "glpat-xxx"
}
}
注意几个关键点：
-
http-basic下的域名必须和composer.json中仓库的url主机名完全一致（比如https://packagist.example.com→ 填packagist.example.com，不能带https://） -
github-oauth只对 github.com 生效；GitHub Enterprise 需走http-basic或gitlab-token（取决于 GitLab 兼容模式） -
gitlab-token是 Composer 2.2+ 新增字段，比用http-basic+private-token更安全（不传密码字段） - 所有 token 必须有足够权限：GitHub token 至少要
read:packages或repo；GitLab token 要read_api+read_repository
调试 auth.json 是否生效？
如果 composer install 报 401 Unauthorized 或 Failed to download vendor/package，别急着改配置，先验证是否真读到了凭据：
- 运行
composer config --global --list | grep -i auth查看全局配置是否识别了auth.json路径 - 加
-v参数重试安装：composer install -v，观察日志里有没有Reading /path/to/auth.json行 - 临时把
auth.json移走，再运行composer install -v，如果错误变成Could not fetch...而不是401，说明原来其实是读到了但凭据无效
真正难排查的是 token 过期、IP 被限流、或 Git 仓库 URL 协议不匹配（比如 https:// 仓库却配了 SSH key 路径）。这类问题不会报“认证失败”，而是卡在连接阶段，得结合 git clone 手动测试确认。
