Composer 本身不提供 IPv4/IPv6 协议偏好开关，完全依赖 PHP curl 或 stream 扩展及系统网络栈行为；解决 IPv6 环境下载失败需通过 php.ini 设置 curl.ipresolve=4、环境变量 CURL_IPRESOLVE=4 或绑定镜像源 IPv4 地址实现。
composer 本身不提供 IPv4/IPv6 协议偏好开关，它完全依赖底层 PHP 的 curl 或 stream 扩展行为，而这些扩展又受操作系统 DNS 解析策略和网络栈控制。你无法通过 composer config 命令设置 “启用 IPv6 下载” —— 这个需求在 Composer 层面不存在。
但如果你遇到「Composer 安装卡在下载、超时、或报错如 Connection refused / Could not resolve host」，且确认是 IPv6 网络环境（比如纯 IPv6 内网、教育网 IPv6-only 出口、或某些云主机 DNS 返回 AAAA 记录但 IPv6 路由不通），那问题本质是：PHP cURL 尝试用 IPv6 连接 packagist.org 或镜像源，但连接失败，又没自动 fallback 到 IPv4。
下面分场景给出可落地的解决路径：
为什么 composer install 在 IPv6 环境下会卡住或失败？
Composer 使用 PHP 的 curl 扩展发起 HTTPS 请求，默认行为由系统 glibc（Linux）或 Windows Sockets 决定：
– DNS 查询同时返回 A（IPv4）和 AAAA（IPv6）记录时，cURL 可能优先尝试 IPv6 地址；
– 若该 IPv6 地址不可达（如防火墙拦截、路由缺失、目标站未开 IPv6），且 cURL 没启用或未及时触发 IPv4 fallback，就会卡死或报错；
– 某些老旧 PHP 版本（如 7.2 以下）的 cURL 绑定逻辑对 IPv6 处理不健壮，尤其在 curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4) 未显式设置时。
强制 Composer 使用 IPv4 的三种实操方法
-
方法一（推荐）：改 PHP 的 cURL 默认行为（全局生效）
编辑你的php.ini，添加或修改：curl.cainfo = "/path/to/cacert.pem" ; 强制所有 curl 请求只走 IPv4 curl.ipresolve = 4
然后重启 PHP（如 php-fpm 或 Apache）。此设置影响所有 PHP curl 调用，包括 Composer。 -
方法二：临时绕过，用环境变量禁用 IPv6 DNS 解析
在运行 composer 前，设置：export CURL_IPRESOLVE=4 composer install
或 Windows：set CURL_IPRESOLVE=4 composer install
注意：该变量仅对当前 shell 有效，且依赖 libcurl ≥ 7.19.4。 -
方法三：换镜像源 + 显式指定 IPv4 地址（最稳）
国内镜像（如阿里云）已支持 IPv6，但若你本地 IPv6 不通，可直接用其 IPv4 地址：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ # 然后手动 ping 确认解析出的是 IPv4： ping mirrors.aliyun.com # 应返回类似 118.31.67.205
若仍解析出 IPv6 地址，可在/etc/hosts（Linux/macOS）或C:\Windows\System32\drivers\etc\hosts（Windows）中强制绑定：118.31.67.205 mirrors.aliyun.com
验证是否真的走了 IPv4
执行带调试的安装命令，观察真实连接地址：
composer install -v 2>&1 | grep "Connecting to"或更直接：
strace -e trace=connect composer install 2>&1 | grep -E "(AF_INET|AF_INET6)"（Linux）—— 如果只看到
AF_INET（即 IPv4），说明生效；若出现 AF_INET6 且后续失败，则需回退到上面任一方法。
别踩坑：IPv6 不是 Composer 的“功能开关”，而是网络层事实
Composer 没有 composer config ipv6 true 这种配置项；composer audit 或 composer update 的安全拦截、插件授权等功能也与 IP 协议版本无关；所谓“支持 IPv6”，仅指它不主动拒绝 IPv6 地址 —— 但一旦网络不通，它不会自救。真正要调的，永远是 PHP 的 curl 行为、DNS 解析策略、或镜像源可达性。生产环境建议统一锁定 IPv4，避免因网络配置漂移导致部署失败。
