Composer 私有仓库认证怎么不进代码：auth.json、环境变量与 CI 检查

不少人跑 CI 执行 composer install 突然碰到 401 报错，第一反应就是把账号和令牌直接写进 composer.json 里。虽然这么做大概率能立刻恢复依赖下载，却会把私有仓库的凭据漏进 Git 提交历史、构建日志还有制品缓存里。更稳妥的思路是，仓库地址留在项目配置里就好，认证数据放到不会被提交的 auth.json、全局凭据文件夹或是 CI 的 COMPOSER_AUTH 环境变量里。

先把仓库配置和认证配置拆开

composer.json 只负责描述“去哪里找包”，本身不适合保存“用什么凭证访问”这类敏感信息。项目里可以正常留私有 Composer 仓库的访问地址，别把用户名、密码或 Bearer 令牌直接拼进 URL 里。

{
  "repositories": [
    {"type": "composer", "url": "https://packages.example.org"}
  ],
  "require": {"company/order-sdk": "^3.2"}
}

Composer 支持的认证存储位置一共四类：项目级 auth.json、全局 auth.json、项目配置内联认证以及 COMPOSER_AUTH 环境变量。其中把认证明文写进项目配置的方式最容易随代码扩散，绝对不能作为团队的默认方案。

本地开发：auth.json 可以用，但必须防止入库

开发机需要长期访问同一个私有仓库时，可以直接用 Composer 内置命令写入项目级认证文件：

composer config http-basic.packages.example.org developer TOKEN_VALUE

生成的 auth.json 和 composer.json 放在同一个目录下，所以这一步做完第一要验收的不是依赖能不能安装成功，而是确认这个文件绝对不会被提交到版本库：

# .gitignore
/auth.json

接着执行 git status --ignored，能看到这个文件已经处于忽略状态才算合格。如果凭据之前已经不小心提交过，光加忽略规则清不掉 Git 历史里的记录，要第一时间吊销旧令牌、签发新令牌，再按团队的安全流程处理历史暴露的问题。

CI 流水线：用 COMPOSER_AUTH 做任务级注入

CI 容器一般都是一次性运行的，没必要为了认证特意创建持久存储文件。把平台密钥库里存储的认证值注入 COMPOSER_AUTH 环境变量，Composer 就能在当前任务进程里直接读取认证数据。

{
  "http-basic": {
    "packages.example.org": {
      "username": "ci-reader",
      "password": "TOKEN_FROM_SECRET_STORE"
    }
  }
}

这里的 JSON 内容要作为敏感密钥单独存，不能直接明文写进流水线的 YAML 配置里。同时流水线日志不要输出完整的环境变量内容，排障的时候只记录目标主机、HTTP 状态码和 Composer 的非敏感诊断信息就够了。

401 不一定是令牌错，先核对主机匹配规则

Composer 会按照认证方式和主机名严格匹配对应的凭据。如果仓库配置用的是 packages.example.org，认证键却写成了 repo.example.org，就算令牌本身完全有效也不会被匹配到。碰到反向代理改端口、从 HTTP 切到 HTTPS、下载地址自动跳转到其他域名的情况，也要确认最终请求的主机名是不是落在已有的认证配置覆盖范围内。

1. 用 composer config --list --auth 核对当前生效的所有认证键，查看的时候注意终端录屏和日志的访问权限。
2. 对照 composer.json 里的仓库 URL，确认域名和端口完全一致。
3. 清理可能携带旧元数据的 Composer 缓存，再用临时的只读令牌复测一次。
4. 确认 CI 侧的密钥作用域已经覆盖当前分支、运行环境或拉取请求类型。

把令牌轮换设计成可回滚的标准步骤

直接删掉旧令牌再创建新令牌的操作，会让并行运行的流水线在切换的时间窗口里随机报错。更稳妥的操作顺序是：先创建权限最小的新令牌，更新密钥库后先跑一条受控测试流水线；确认私有包下载全部正常后，再吊销旧令牌，最后清理长期缓存和各处遗留的旧环境变量。

流水线的验收至少要覆盖三种状态：新令牌访问成功、旧令牌已经失效、缺少密钥的情况下任务会明确失败。这样既能验证轮换操作完全生效，也能避免脚本悄悄回退读取开发机全局的遗留凭据。

常见问题

auth.json 能不能提交到私有 Git 仓库？

不建议这么做。哪怕是私有仓库，也可能被更多团队成员、机器人账号、镜像同步系统和备份服务读取，凭据会被扩散到更多不可控的位置。

COMPOSER_AUTH 是否绝对不会泄露？

不是。错误的调试命令、环境全量转储或是 Shell 历史记录都有可能把它暴露出来，所以必须配合日志脱敏和最小权限的密钥规则一起使用。

本地开发和 CI 场景可以共用一个令牌吗？

不建议。开发者日常使用的令牌和 CI 专用的只读令牌应该分开签发，后续按用途吊销、审计、轮换的时候都更方便。

明明凭据配置正确为什么还是下载失败？

接着核对仓库最终跳转的域名、令牌对目标包的读取权限、代理配置以及私有仓库对目标包版本的可见性，不用急着重试重写密码。

收口检查

私有仓库认证的核心不是换个地方存同一段密码，而是把仓库声明、凭据注入和令牌生命周期拆成三层可以独立校验的逻辑。本地开发环境保证 auth.json 不会被提交到代码库，CI 从密钥库注入 COMPOSER_AUTH，令牌轮换时让新旧凭据短暂并行后再完成旧凭据的失效验证，就能避免一次临时 401 报错的修复，演变成长期的凭据泄露风险。