Composer的COMPOSER_AUTH环境变量如何配置和使用？

COMPOSER_AUTH 是 Composer 用于安全配置私有仓库认证的环境变量，支持 HTTP 基本认证、GitHub OAuth、GitLab Token 等，常用于 CI/CD 环境；其值为 JSON 字符串，包含 http-basic、github-oauth、gitlab-token 等字段，优先级高于全局 auth.json 但低于项目级 auth.json，需注意 JSON 格式正确性和敏感信息保护。

Composer 的 COMPOSER_AUTH 环境变量用于在不修改本地配置文件的前提下，安全地提供私有仓库、GitHub API 令牌或其他需要认证的资源访问凭证。它常用于 CI/CD 环境或共享开发环境中。

什么是 COMPOSER_AUTH

COMPOSER_AUTH 是一个 JSON 格式的环境变量，Composer 在运行时会自动读取它，并将其解析为认证信息。支持的类型包括 HTTP 基本身份验证、Bearer Token、OAuth 等，主要用于：

• 访问私有的 Packagist 镜像或 Satis 仓库
• 提高 GitHub API 请求限制（通过 personal access token）
• 连接需要身份验证的 VCS 或 HTTP 仓库

配置格式说明

该变量内容是 JSON 字符串，结构中可包含多个认证源。常见字段有：

• http-basic：用于 HTTP 基本身份验证
• github-oauth：用于 GitHub 访问令牌
• gitlab-token：用于 GitLab 私有项目

示例：

{
    "http-basic": {
        "private-repo.example.com": {
            "username": "user",
            "password": "pass"
        }
    },
    "github-oauth": {
        "github.com": "your_github_token_here"
    },
    "gitlab-token": {
        "gitlab.com": "your_gitlab_token"
    }
}

如何设置环境变量

根据操作系统和使用场景，可通过以下方式设置：

Linux / macOS（终端临时设置）

export COMPOSER_AUTH='{"github-oauth":{"github.com":"YOUR_TOKEN"}}'
composer install

Linux / macOS（永久写入 shell 配置）

考拉新媒体导航

考拉新媒体导航——新媒体人的专属门户网站

下载

将 export 命令加入 ~/.bashrc 或 ~/.zshrc：

echo 'export COMPOSER_AUTH='\''{"github-oauth":{"github.com":"YOUR_TOKEN"}}'\''' >> ~/.zshrc
source ~/.zshrc

Windows（命令行）

set COMPOSER_AUTH={"github-oauth":{"github.com":"YOUR_TOKEN"}}
composer install

Windows（PowerShell）

$env:COMPOSER_AUTH='{"github-oauth":{"github.com":"YOUR_TOKEN"}}'
composer install

CI/CD 中（如 GitHub Actions）

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: composer install
        env:
          COMPOSER_AUTH: '{ "github-oauth": { "github.com": "${{ secrets.GITHUB_TOKEN }}" } }'

使用注意事项

确保遵循以下最佳实践以避免问题：

• JSON 必须是合法字符串，注意引号转义（尤其在 Shell 中）
• 敏感信息不要硬编码在脚本或版本控制中
• COMPOSER_AUTH 优先级高于全局 auth.json，但低于项目级 auth.json（如果显式配置）
• 若同时使用多种认证方式，合并写在一个 JSON 对象中即可
• GitHub 自 2021 年起要求私有库访问使用 token，否则可能触发 API 限流

基本上就这些。正确配置后，Composer 会在拉取依赖时自动使用对应凭据，无需交互。关键是保证环境变量有效且格式正确。