解决Composer在IPv6网络环境下连接超时的问题

composer在纯ipv6网络下卡住是因为stream_socket_client()优先尝试IPv6但TLS握手失败且无IPv4回退；根治方案是修改/etc/gai.conf添加precedence ::ffff:0:0/96 100，提升IPv4映射地址优先级。

为什么 composer install 在纯 IPv6 网络下会卡住或超时

Composer 默认使用 php 的 stream_socket_client() 建立 httpS 连接，而该函数在某些系统（尤其是未正确配置 IPv6 DNS 或缺乏双栈支持的环境）中，可能优先尝试 IPv6 地址但无法完成 TLS 握手，导致 30 秒级超时后才回退到 IPv4 —— 如果系统根本没启用 IPv4（如某些容器或教育网纯 IPv6 环境），就会一直卡在 Resolving dependencies 或 Downloading... 阶段。

临时绕过：强制 Composer 使用 IPv4

最直接有效的方式是让 Composer 所有 HTTP 请求走 IPv4。这不修改全局网络配置，只影响当前命令：

• 运行前设置环境变量：export COMPOSER_HTTP_PROXY=http://127.0.0.1:8888（仅当你有本地 IPv4 代理时适用）
• 更通用的做法是用 curl 的 --ipv4 行为模拟：通过 php -d allow_url_fopen=1 -d default_socket_timeout=10 -d openssl.cafile=/path/to/cacert.pem 启动，但实际更简单的是重写 Composer 的 HTTP 客户端行为
• 推荐做法：在执行命令前加 PHP_OPTIONS="-d disable_functions=" 并配合 curl 驱动，但真正轻量且生效的是——直接禁用 IPv6 解析

执行以下任一命令即可立即生效：

php -d variables_order=EGPCS -d allow_url_fopen=1 -d default_socket_timeout=15 -d openssl.cafile=$(php -r "echo dirname(dirname(dirname(realpath('vendor/composer/autoload_real.php')))).'/ca-bundle.crt';") /usr/bin/composer install --no-plugins

但更实用的是在 composer.json 中添加：

"config": {     "github-protocols": ["https"],     "disable-tls": false,     "secure-http": true }

这些本身不解决 IPv6，关键在下一步。

根治方案：配置 cURL 使用 IPv4 强制解析

Composer 从 2.2 开始默认使用 cURL（而非 stream），因此可通过 cURL 配置控制 IP 版本。需确保你的 PHP 编译时启用了 cURL 扩展，并且 cURL 版本 ≥ 7.19.4。

• 创建或编辑 ~/.curlrc（linux/macos）或 %HOME%_curlrc（windows），加入：resolve = "*:443:127.0.0.1" —— 但这会把所有 443 域名解析成 127.0.0.1，不可取
• 正确做法是让 Composer 使用 CURLOPT_IPRESOLVE 选项：需通过自定义 HttpClient 实现，但太重
• 最简稳解：设置环境变量 COMPOSER_NO_INTERACTION=1 + 强制系统级 DNS 解析走 IPv4 —— 即修改 /etc/gai.conf（Linux）

在 /etc/gai.conf 末尾添加：

precedence ::ffff:0:0/96  100

这条规则让 IPv4-mapped IPv6 地址（如 ::ffff:127.0.0.1）获得最高优先级，从而避免原生 IPv6 连接失败。重启终端或重新加载网络服务后，composer install 即可正常解析 packagist.org 等域名。

验证是否仍在尝试原生 IPv6 连接

用 strace 或 tcpdump 直接观察连接行为比猜更可靠：

• 运行 strace -e trace=connect,sendto,recvfrom php /usr/bin/composer require monolog/monolog，观察输出中是否有 connect(3, {sa_family=AF_INET6, ...}, 28) 类似行；若持续出现且无后续 sendto，说明 IPv6 连接卡死
• 更轻量方式：curl -v https://packagist.org/packages.json 2>&1 | grep "Connected to"，看输出里是 127.0.0.1 还是 ::1 或真实 IPv6 地址
• 如果 curl 正常但 composer 不行，大概率是 Composer 内部未继承系统 cURL 配置，此时应升级 Composer 至 latest（composer self-update）并确认 php -m | grep curl 输出非空

IPv6 环境下的 Composer 问题，本质不是 Composer 本身缺陷，而是它依赖的底层网络栈暴露了系统 DNS 和协议栈配置的缝隙。填上 /etc/gai.conf 这一条，往往比改代码、换镜像、加代理更彻底。