Composer config 无法禁用 IPv6，因其仅管理自身配置项，不控制 PHP cURL 或系统网络栈；真正有效的方法是设置环境变量 COMPOSER_IPV4=1，强制所有 HTTP 请求使用 IPv4。
为什么 composer config 不能直接禁用 IPv6
很多人尝试运行 composer config -g github-protocols https 或类似命令，以为能“关闭 IPv6”，但实际无效——composer config 管理的是 Composer 自身的配置项（如仓库地址、认证 token、超时时间等），不控制底层 PHP cURL 或系统网络栈的 IP 协议行为。IPv6 连接问题本质是 PHP 的 curl 扩展在解析域名时优先尝试 AAAA 记录，而目标服务器或中间网络不支持 IPv6，导致连接卡住或超时。
真正起效的禁用 IPv6 方法：改 PHP 的 curl 配置
Composer 底层依赖 PHP 的 curl 扩展发起 HTTP 请求。要强制走 IPv4，必须让 cURL 在 DNS 解析后只使用 A 记录（IPv4 地址）。PHP 本身不提供全局开关，但可通过以下两种方式干预：
- 在
composer.json中通过http-basic或自定义repositories无法绕过 DNS 解析逻辑，无效 - 唯一稳定生效的方式：在调用
curl_setopt()时设置CURLOPT_IPRESOLVE为CURL_IPRESOLVE_V4 - Composer 源码中已预留该能力：从 Composer 2.2+ 起，支持通过环境变量
COMPOSER_IPV4强制所有 HTTP 请求走 IPv4
所以最简单实操方案就是：
COMPOSER_IPV4=1 composer install
或者永久生效（Linux/macOS）：
echo 'export COMPOSER_IPV4=1' >> ~/.bashrc && source ~/.bashrc
Windows 用户可在系统环境变量中添加 COMPOSER_IPV4 = 1。
验证是否生效：看请求日志和 DNS 行为
加 -vvv 参数可观察真实请求过程：
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
COMPOSER_IPV4=1 composer require monolog/monolog -vvv
你会看到类似输出：
Downloading https://packagist.org/packages.json [debug] Using HTTP/2 with IPv4 only
若没加 COMPOSER_IPV4=1，且系统有 IPv6 网络，日志中可能先卡在 Trying [2a02:xxxx::1]:443... 几秒后再 fallback 到 IPv4 —— 这就是典型的 IPv6 超时拖慢 Composer。
额外验证方法：用 strace（Linux）或 tcpdump 抓包，确认无 IPv6 地址连接尝试；或临时禁用本机 IPv6（sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1）对比耗时差异。
替代方案与坑点提醒
有人会改 /etc/hosts 把 packagist.org 映射到 IPv4 地址，这看似可行，但存在严重隐患：
- packagist.org 的 IP 经常变动，硬编码会导致后续请求 404 或证书错误
- CDN 域名（如
api.github.com）也受同样影响，需一并处理，维护成本高 - Composer 2.5+ 默认启用 HTTPS 严格校验，host 文件伪造可能触发
SSL certificate problem: unable to get local issuer certificate
还有人试图用 composer config -g http-proxy 配代理来绕过，但这解决的是访问限制，不是 IPv6 协议层阻塞，且代理本身若支持 IPv6，问题依旧存在。
真正干净、可复现、无需维护的解法，只有 COMPOSER_IPV4=1。它被 Composer 官方文档明确支持，且不依赖外部工具或系统配置变更。
