COMPOSER_AUTH是Composer用于安全认证私有仓库的环境变量，支持HTTP Basic、Bearer Token、OAuth等类型，通过JSON格式定义凭据并注入CI/CD环境，避免硬编码。典型用法如设置GitHub OAuth Token或私有镜像的用户名密码，配合CI平台的密钥管理功能实现自动安装私有依赖，需遵循最小权限、定期轮换和日志脱敏等安全实践。
在CI/CD环境中使用 Composer 时，有时需要访问私有包仓库（如私有 Packagist 镜像、GitHub Private Repositories 或私有 Satis 服务器），这些资源通常需要身份验证。为了安全地传递认证信息，Composer 提供了 COMPOSER_AUTH 环境变量机制，避免将敏感凭据硬编码到代码或配置文件中。
什么是 COMPOSER_AUTH？
COMPOSER_AUTH 是一个环境变量，允许你以 JSON 格式定义认证信息，Composer 在运行时会自动读取并用于请求私有资源。支持的认证类型包括：
- HTTP Basic 认证：用户名和密码
- Bearer Token：如 GitHub Personal Access Token
- OAuth Tokens：如 GitLab 的 deploy token
- SSH 密钥配合代理（间接支持）
关键优势是：无需修改项目中的 auth.json 文件，所有凭证通过环境注入，适合自动化流程。
如何设置 COMPOSER_AUTH
你需要将认证信息构造成 JSON 字符串，并将其作为环境变量传入 CI/CD 运行环境。格式如下：
{
"http-basic": {
"repo.example.com": {
"username": "your-username",
"password": "your-token-or-password"
}
},
"github-oauth": {
"github.com": "your-github-token"
},
"gitlab-token": {
"gitlab.com": "your-gitlab-token"
},
"bearer": {
"private.registry.com": "your-jwt-token"
}
}
然后将其转为单行字符串并设置为环境变量：
COMPOSER_AUTH='{"http-basic": {"repo.example.com": {"username": "user", "password": "pass"}}, "github-oauth": {"github.com": "abc123"}}'
在 CI 脚本中，这通常通过 CI 平台的“秘密变量”功能设置，例如：
-
GitHub Actions：在 Settings > Secrets 中添加名为
COMPOSER_AUTH的 secret - GitLab CI：在 Settings > CI / CD > Variables 中添加
- Bitbucket Pipelines：在 Repository settings > Repository variables 中设置
然后在 CI 脚本中无需显式导出，平台会自动注入；或明确写入：
export COMPOSER_AUTH=$COMPOSER_AUTH composer install --no-interaction
常见使用场景示例
使用 GitHub Private Repository 作为依赖
- 生成一个具有
repo权限的 GitHub Personal Access Token - 在
composer.json中声明仓库：
"repositories": [
{
"type": "vcs",
"url": "https://github.com/your-org/private-package.git"
}
]
- 设置
COMPOSER_AUTH：
{"github-oauth": {"github.com": "ghp_XXXXXXXXXXXXXXXXXXXXXXXX"}}
Composer 即可在 composer install 时拉取私有库。
访问私有 Packagist 镜像（如 Toran Proxy 或 private Packagist）
- 这类服务通常提供 HTTP Basic 认证方式
- 设置：
{"http-basic": {"packagist.your-company.com": {"username": "ci-user", "password": "api-token"}}}
安全最佳实践
-
绝不提交 auth.json 到版本控制：确保
auth.json在 .gitignore 中 - 使用最小权限令牌：CI 使用的 token 应仅具备读取依赖的权限，避免写操作
- 定期轮换令牌：尤其在多人协作或高安全要求项目中
-
启用 CI 日志脱敏：确保 CI 平台能隐藏
COMPOSER_AUTH等敏感变量输出 - 避免在脚本中 echo 或打印该变量
基本上就这些。通过合理使用 COMPOSER_AUTH，你可以让 CI/CD 流程安全、自动地安装私有依赖，同时保持项目的可移植性和安全性。不复杂但容易忽略细节。
