composer如何配置auth.json_composer认证文件教程【安全】

auth.json须按优先级放置：项目根目录仅限本项目，用户主目录（权限≤600）供全局使用；结构仅支持http-basic和github-oauth键，域名须精确匹配，用户名密码字段名固定。

auth.json 文件该放哪儿才生效

composer 查找 auth.json 有固定优先级：当前项目根目录下的 auth.json > 用户主目录的 auth.json（即 ~/.composer/auth.json 或 %APPDATA%Composerauth.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 ≠ <a href="https://www.php.cn/link/87714b79a84563173e3d0088286f51a7">https://www.php.cn/link/87714b79a84563173e3d0088286f51a7</a>）
• 每个仓库独立配置，不支持通配符或子路径继承
• 用户名密码字段名固定为 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 私仓需开启 api scope，并确认 token 绑定的 group/project 权限足够

• 若用 Nexus，检查 realm 是否为 Nexus Realm，且 token 对应用户已分配 nx-repository-view-<em>-</em>-* 角色

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 状态码。