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.，都会让整个私有包拉取链静默崩掉。
