Composer的COMPOSER_AUTH环境变量有何用途？ (CI/CD认证)

composer_AUTH 环境变量替代的是手动运行 composer config –auth 生成的 auth.json 文件内容，以 json 字符串形式在内存中提供认证凭据，避免写入磁盘，适用于无交互的 CI/CD 构建环境。

COMPOSER_AUTH 环境变量用于在无交互的 CI/CD 环境中，向 Composer 提供私有仓库（如 gitLab、github Packages、Packagist Pro、自建 Satis/SatisPress）所需的认证凭据，避免执行 composer install 时卡在交互式密码输入或因 401 错误中断。

它替代的是什么？

它等价于手动运行 composer config --auth http-basic.example.com username Token 后生成的 auth.json 文件内容，但无需写入磁盘文件，适合只读容器或临时构建环境。

• 不覆盖项目根目录下的 auth.json（如果存在且未被 --no-auth 禁用，Composer 仍会优先读取它）
• 不替代 ~/.composer/auth.json（用户级配置），仅作用于当前进程
• 值必须是合法 JSON 字符串，键名需严格匹配 Composer 认证类型（如 http-basic、github-oauth、gitlab-token）

典型格式与常见错误

错误常出现在 JSON 转义、多余空格、协议/域名拼写不一致 —— 这些都会导致 Composer 静默忽略认证或报 Invalid credentials for ...。

• http-basic 域名必须和 composer.json 中仓库 URL 的 host 完全一致（例如 "https://packages.example.com" 对应 "packages.example.com"，不能写成 "https://packages.example.com" 或带端口却没在 URL 中体现）
• Token 或密码中若含 /、=、+ 等字符，必须正确 JSON 转义（Shell 中建议用单引号包裹整个 JSON，避免 Shell 解析干扰）
• GitHub OAuth Token 应放在 github-oauth 下，不是 http-basic；GitLab Personal access Token 则对应 gitlab-token

{"http-basic": {"packages.example.com": {"username": "ci-bot", "password": "ghp_xxx..."}}, "github-oauth": {"github.com": "xxx..."}}

CI/CD 中如何安全设置？

绝不能硬编码进 .gitlab-ci.yml 或 workflow.yaml。必须通过平台提供的密文机制注入：

• GitLab CI：设为 protected variable，Key 为 COMPOSER_AUTH，Value 为转义后的 JSON 字符串
• GitHub Actions：用 env: + ${{ secrets.COMPOSER_AUTH }}，且 secret 值需提前用 jq -n --arg v "$VALUE" '{$v}' 类工具验证格式
• 确保 runner 容器内没有残留的 auth.json（可在 job 开头加 rm -f ~/.composer/auth.json ./auth.json）

调试失败时先检查什么？

Composer 不会明确告诉你 COMPOSER_AUTH 是否被解析失败，只会报 401 或 “Could not fetch” —— 此时应开启详细日志并确认实际请求头：

• 加 -v 参数运行：composer install -v 2>&1 | grep -A5 -B5 'Authorization|401'
• 检查是否因 composer.json 中仓库 type 是 artifact 或 package 而根本没走 HTTP 认证流程
• 运行 composer config --list --auth（注意加 --auth）看是否输出了预期配置 —— 若为空，说明 COMPOSER_AUTH 格式非法或未生效

真正麻烦的不是设这个变量，而是它的 JSON 结构必须和 Composer 内部解析逻辑严丝合缝；少一个引号、多一个空格、host 多了个 www.，都会让整个私有包拉取链静默崩掉。