composer中auth.json文件的作用_composer配置私有令牌授权方法【详解】

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%Composerauth.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。