Composer 读取 auth.json 是为向私有仓库或需认证的 Composer 仓库发送带认证的 HTTP 请求，文件为明文 JSON，须严格控制权限；按 COMPOSER_AUTH 环境变量、项目根目录、全局配置目录顺序查找；Basic Auth 域名须完全匹配 host，GitHub/GitLab 应分别用 github-oauth 或 gitlab-token 字段；禁止提交至 Git，推荐 chmod 600 并优先使用环境变量注入。
Composer 读取 auth.json 是为了向私有仓库（如 GitLab、GitHub Packages、Packagist.org 的 private packages）或需要 Basic Auth 的 Composer repository 发送带认证的 HTTP 请求。它不用于系统级登录，也不加密存储——文件内容是明文 JSON，必须严格控制权限。
auth.json 放哪儿才生效
Composer 按顺序查找 auth.json，找到即停止：
-
COMPOSER_AUTH环境变量（值为 JSON 字符串，优先级最高） - 当前项目根目录下的
auth.json - 全局配置目录（
composer config --global home输出路径）下的auth.json
生产环境建议用项目级 auth.json 并加入 .gitignore；CI/CD 中推荐用 COMPOSER_AUTH 注入，避免文件残留。
Basic Auth 配置格式与常见错误
私有 Packagist 或自建 Satis 仓库通常要求 Basic Auth。格式必须是：
{
"http-basic": {
"repo.example.com": {
"username": "your-username",
"password": "your-token-or-password"
}
}
}
容易出错的地方：
- 域名必须完全匹配仓库 URL 的 host 部分（不含协议、路径），比如仓库是
https://packages.example.org，这里就得写"packages.example.org" -
username和password是字符串，不能省略引号，也不能用null或空字符串代替 - 如果密码含特殊字符（如
/、@），Base64 编码不是必须的，但确保未被 shell 或 CI 工具意外截断
GitHub / GitLab token 的正确用法
GitHub Packages、GitLab API 仓库等使用的是 Bearer Token，不是 Basic Auth，不能塞进 http-basic。应使用 github-oauth 或 gitlab-token：
{
"github-oauth": {
"github.com": "ghp_xxx..."
},
"gitlab-token": {
"gitlab.example.com": "glpat-xxx..."
}
}
注意：
-
github-oauth只对 github.com 生效；自托管 GitHub Enterprise 要用gitlab-token形式并配对应 host - GitLab token 必须有
read_api权限（Private Tokens）或apiscope（OAuth Apps） - 这些字段不会被 Composer 自动用于普通
git clone，仅影响通过 Composer Repository 协议拉取元数据和 ZIP 包的请求
权限与安全红线
auth.json 是敏感凭证载体，任何疏忽都可能导致凭据泄露：
- Linux/macOS 下运行
chmod 600 auth.json，禁止 group/o 可读 - 绝不在 Git 提交中包含该文件，即使加了
.gitignore，也要检查历史提交是否误传过 - 不要在
composer.json中硬编码 token；config.platform或scripts里调用composer config动态写入也属高危操作 - PHP 进程若以 webserver 用户（如 www-data）运行且能读取项目目录，就可能被恶意脚本读取该文件——此时应改用环境变量注入
最常被忽略的一点：Composer 会缓存远程包元数据（包括从认证仓库获取的内容），这些缓存本身不加密，且默认不校验响应签名。一旦凭据泄漏，攻击者可伪造响应污染本地 cache，进而安装恶意包。所以凭据管理必须前置，不能依赖“反正 cache 是临时的”这种想法。
