解决Composer在IPv6网络环境下连接超时的问题-composer-PHP中文网

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

解决composer在ipv6网络环境下连接超时的问题

为什么 `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。

github项目持续追踪

GitHub 项目更新追踪工具 - 自动检查多个 GitHub 项目的 Releases 和 CHANGELOG，生成更新摘要与影响分析报告。支持自动化定时任务。如何使用最简单的方式：直接用自然语言告诉我你可以说我会做「检查 GitHub 更新」检查最新版本「添加 vscode」追踪新项目「停止追踪 xxx」移除项目「暂停更新检查」暂停自动化「给我看 openclaw 报告」展示报告触发词：「追踪项目更新」「检查 GitHub 更新」「项目更新报告」「设置更新提醒」

下载

创建或编辑 ~/.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 输出非空