auth.json须按优先级放置：项目根目录仅限本项目，用户主目录（权限≤600）供全局使用；结构仅支持http-basic和github-oauth键，域名须精确匹配，用户名密码字段名固定。
auth.json 文件该放哪儿才生效
Composer 查找 auth.json 有固定优先级：当前项目根目录下的 auth.json > 用户主目录的 auth.json（即 ~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）。
多数人配了却没生效，是因为放错了位置——尤其在 CI/CD 或 Docker 环境里，容易误以为写进项目根目录就自动被全局读取，其实它只对当前项目生效；若想让所有项目共用凭据，必须放到用户级路径。
- 项目级认证：把
auth.json放在项目根目录（和composer.json同级），仅影响本项目 - 全局认证：放在用户主目录下，但要注意权限 —— Linux/macOS 下需确保文件权限 ≤
600，否则 Composer 会静默忽略 - Git 里千万别提交：这个文件含敏感凭据，务必加进
.gitignore，CI 中应通过 secrets 注入而非硬编码
auth.json 的结构不能套用 JSON Schema
auth.json 不是自由格式 JSON，它的顶层键只有两个合法值：http-basic 和 github-oauth（已弃用，新版推荐用 token），其他字段会被直接忽略。常见错误是照着 API 文档拼了个“看起来很全”的 JSON，结果认证始终失败。
- 必须用
http-basic包裹私仓地址，且域名要精确匹配（比如repo.example.com≠@#@#@#@#@#@#@#@#@#@0） - 每个仓库独立配置，不支持通配符或子路径继承
- 用户名密码字段名固定为
username和password，拼错成user或passwd都无效
{
"http-basic": {
"repo.example.com": {
"username": "my-token",
"password": ""
}
}
}
注意：很多私仓（如 Nexus、Artifactory）要求将 token 填在 username 字段，password 留空 —— 这不是 bug，是它们的 HTTP Basic 实现方式。
使用 token 替代密码时的常见报错
最典型的是 401 Unauthorized，但 Composer 默认不打印详细响应头，容易误判为网络或配置问题。真实原因常是：
token 权限不足（例如只读 token 无法安装 dev 分支包）
token 已过期或被吊销（尤其 GitHub Personal Access Token 在 2021 年后强制要求 scope）
私仓启用了双因素认证（2FA）但未在 token 中启用对应权限（如
read:packages）-
GitHub 推荐用 fine-grained token，scope 至少勾选
read:packages和delete:packages（如果要发布） GitLab 私仓需开启
apiscope，并确认 token 绑定的 group/project 权限足够若用 Nexus，检查 realm 是否为
Nexus Realm，且 token 对应用户已分配nx-repository-view---*角色
CI 环境中 auth.json 的安全注入方式
硬编码、挂载明文文件、甚至 base64 解码都算高危操作。真正安全的做法是利用 CI 自带的 secret 注入机制，在运行时动态生成 auth.json。
- GitHub Actions：用
echo "${{ secrets.COMPOSER_AUTH }}" > auth.json，其中COMPOSER_AUTH是预设的 JSON 字符串（注意转义双引号） - GitLab CI：通过
before_script写入，变量值需是合法 JSON 字符串，不是对象 - Docker 构建阶段：绝不要 COPY 明文
auth.json，改用--secret+DOCKER_BUILDKIT=1配合RUN --mount=type=secret
关键点：任何写入磁盘的操作都要确保文件权限立即设为 600，且构建结束后清理临时文件 —— Composer 本身不会校验权限，但系统级防护（如 umask 或安全扫描）可能拦截。
复杂点在于不同私仓对 token 类型、scope、过期策略、realm 名称的要求差异极大，同一份 auth.json 很难跨平台复用；更麻烦的是，错误信息往往只显示 “Could not fetch” 或 “Invalid credentials”，得靠 composer install -v 才能看到底层 HTTP 状态码。
