auth.json是Composer本地存储私有仓库认证凭据的配置文件，不参与版本控制；按项目根目录→用户主目录顺序查找，支持http-basic、github-oauth、gitlab-token等字段，域名必须与请求地址完全一致。
auth.json 是 Composer 用来存储私有仓库认证凭据的配置文件，它不参与版本控制，只在本地生效。它的核心作用是让 composer install 或 composer update 能自动携带 token、用户名/密码等凭证，访问需要授权的私有 Packagist、GitLab、GitHub（私有 repo）、Bitbucket 等源。
auth.json 放在哪？优先级怎么算？
Composer 按以下顺序查找 auth.json，找到即停止：
- 当前项目根目录下的
auth.json - 用户主目录下的
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows）
项目级 auth.json 优先级更高，适合多团队协作中为不同项目配不同 token；全局级适合个人开发环境统一配置 GitHub/GitLab 的 personal access token。
auth.json 的基本结构和字段含义
最常见写法是按仓库域名组织认证信息，http-basic 用于 HTTP Basic Auth（如私有 Packagist），github-oauth 和 gitlab-token 是专用字段，避免手动拼 Header。
示例：
{
"http-basic": {
"packagist.example.com": {
"username": "myuser",
"password": "apitoken_or_apikey"
}
},
"github-oauth": {
"github.com": "ghp_xxx..."
},
"gitlab-token": {
"gitlab.example.com": "glpat-xxx..."
}
}
注意：github-oauth 值必须是 GitHub Personal Access Token（至少带 read:packages 权限）；gitlab-token 对应 GitLab 的 Personal Access Token（需 read_api）；http-basic 中的 password 字段实际可填 API token（很多私有 Packagist 实现把 token 当 password 用）。
为什么不能把 auth.json 提交到 Git？
因为里面是明文凭据，提交即泄露权限。Composer 默认会忽略项目根目录的 auth.json（.gitignore 自动包含该行），但如果你手动删了 ignore 规则，或误用 composer config --auth 写入项目配置，就可能意外提交。
安全建议：
- 始终检查
.gitignore是否含/auth.json - 不用
composer config --auth repository.example.com username password写项目级配置（它会写进项目composer.json的config字段，更危险） - CI 环境中不要生成
auth.json文件，改用环境变量 +composer config命令动态注入（如 GitHub Actions 可用composer config http-basic.packagist.example.com ${{ secrets.USER }} ${{ secrets.TOKEN }}）
常见错误：401 Unauthorized 或 Could not fetch
执行 composer update 时遇到这类报错，90% 是 auth.json 配置不匹配：
- 域名拼错（比如写了
https://gitlab.example.com，但auth.json里是gitlab.example.com—— 必须完全一致，不含协议和路径） - token 过期或权限不足（GitHub token 缺少
read:packages，GitLab token 缺少read_api） - 私有 Packagist 返回 401，但你配的是
github-oauth字段（应该用http-basic） - 用了自签名 HTTPS 证书但没配
"secure-http": false（仅调试用，不推荐）
调试技巧：运行 composer config --list --global 查看全局生效的 auth 配置；用 curl -v -u "$USER:$TOKEN" https://packagist.example.com/packages.json 手动验证凭证是否有效。
真正容易被忽略的是域名粒度——它必须和 Composer 请求的源地址**完全一致**，包括子域、端口（如有），且不带协议。一个字母错，认证就失效，而错误提示往往不直接指向 auth.json。
