composer如何设置HTTP User-Agent用于私有仓库识别？（custom headers配置）

composer 不支持通过 config 命令设置 user-agent，需在 composer.json 的 repositories 中为 composer 类型仓库配置 options.headers.user-agent；该设置仅影响元数据请求，不生效于 zip/tar 下载阶段。

composer config 如何设置自定义 User-Agent

Composer 本身不提供直接配置 User-Agent 的命令行选项或全局配置项，config 命令能设的 http 头只有 http-basic 认证和代理，User-Agent 不在其中。想让它发请求时带指定 UA，必须绕过默认行为，改用 composer.json 的 repositories 配置 + 自定义 options。

在 repositories 中用 options 添加 custom headers

私有仓库（如 Satis、private Packagist 或自建 Artifactory）常依赖 User-Agent 区分客户端类型或做访问统计。Composer 支持在每个仓库配置中通过 options 注入 HTTP 头，但仅对 composer 类型仓库生效（即含 packages.json 的源），不适用于 vcs 或 package 类型。

• options 必须写在仓库对象内，不是全局配置
• 只支持 headers 子字段，且 key 必须是标准 HTTP 头名（大小写不敏感，但建议首字母大写）
• 值会被原样发送，不会自动编码或拼接；避免含换行或控制字符
• 示例写法：

{     "repositories": [         {             "type": "composer",             "url": "https://your-private-repo.example.com",             "options": {                 "headers": {                     "User-Agent": "my-company-composer/2.4.0 (php 8.2)"                 }             }         }     ] }

为什么 vendor/bin/composer install 仍不生效？

常见失效原因不是配置错，而是 Composer 的请求分阶段：元数据获取（packages.json）走 repositories 配置，但下载 ZIP/TAR 包时会跳过 options，改用内置 HTTP 客户端，此时 UA 固定为 Composer/2.x。这意味着：

• 私有仓库若只靠 UA 拦截元数据请求（比如限流或鉴权），该配置有效
• 若需在包下载阶段也被识别，必须在服务端反向代理层（如 nginx）补全头，或改用 artifact 仓库模式配合自定义 downloader
• 运行 composer clear-cache 后再 install，否则可能缓存旧响应，UA 看似没变

PHP curl 扩展版本与 header 覆盖风险

Composer 底层用 PHP 的 curl 发起请求，而 curl_setopt($ch, CURLOPT_USERAGENT, ...) 会覆盖 headers 里设的 User-Agent。如果项目中启用了自定义 curl 钩子（比如某些企业安全插件），或者系统级 curl 配置强制设 UA（如 CURLOPT_USERAGENT 在 php.ini 中预设），你的 options.headers.User-Agent 就会被静默丢弃。

• 验证是否生效：启用 COMPOSER_HTTP_PROXY=http://localhost:8080 并用 mitmproxy 抓包，看实际发出的请求头
• 低版本 curl（
• Windows 下若使用 WSL2，注意宿主机防火墙或代理软件可能重写 UA

真正起作用的永远是最后被 curl 执行的那一行 setopt，而不是你写在 JSON 里的那行字。