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 里的那行字。
