composer install/update 卡在0%或反复断连的根本原因是curl连接层配置不当，包括未启用长连接、超时过短及国内镜像代理异常，导致tcp被中间设备切断；临时方案用--prefer-dist，永久方案需全局配置timeout=600并启用重试。
Composer install/update 卡在 Downloading（0%）或反复断连
根本原因不是网速慢，而是 Composer 默认用 curl 下载时未启用长连接、超时太短，加上国内源镜像偶尔响应延迟，导致 TCP 连接被中间设备（如运营商 NAT、防火墙）主动切断。你看到的“停滞”其实是重试失败后静默等待，而非真正卡住。
- 运行
composer install -vvv，如果末尾反复出现Connection timed out或Failed to decode response，基本可确认是连接层问题 - 临时解决：加
--prefer-dist强制走 zip 包（比 git clone 更稳定），但前提是包有 dist 发布 - 永久修复：改 Composer 全局配置，延长超时并启用重试：
composer config -g repos.packagist.org {\"url\": \"https://packagist.org\", \"type\": \"composer\", \"options\": {\"http\": {\"timeout\": 600, \"max_redirects\": 20, \"ignore_errors\": true}}} - 注意：不要手动改
composer.json里的repositories，全局 config 才影响所有项目
用国内镜像源仍卡住，甚至返回 503 或空响应
清华、阿里等镜像站本身没问题，但它们对上游（Packagist）的反向代理逻辑会放大连接异常——尤其当你本地 DNS 解析不稳定，或镜像站临时同步延迟时，composer 会因 HTTP 头缺失或状态码异常直接放弃，不重试。
- 验证是否真连上了镜像：执行
curl -I https://mirrors.aliyun.com/composer/，看是否返回200 OK；若返回503或超时，换源 - 推荐切换为
https://packagist.phpcomposer.com（已停更，不建议）或直接用https://packagist.org+ 代理（见下一条） - 最稳方案：配系统级代理（非 Composer 内置 proxy），让所有 HTTPS 流量走本地 socks5：
export https_proxy=socks5h://127.0.0.1:1080
，再运行composer update - Windows 用户注意：
set https_proxy=...仅对当前 cmd 有效；PowerShell 要用$env:https_proxy="..."
PHP cURL 扩展启用了 SSL 验证，但系统 CA 证书过旧
Composer 底层依赖 PHP 的 curl 扩展，若系统 OpenSSL 版本低（如 CentOS 6 自带的 1.0.1e），或 CA 证书路径不对（curl.cainfo 指向了空文件或过期 bundle），就会在 TLS 握手阶段失败，表现为下载瞬间中断、无错误提示、进度条不动。
- 检查命令：
php -r "print_r(curl_version());"看ssl_version和features是否含CURL_VERSION_SSL - 查 CA 路径：
php -i | grep cainfo，若输出为空或路径不存在，手动指定：echo "curl.cainfo=/etc/ssl/certs/ca-bundle.crt" >> /usr/local/etc/php/conf.d/docker-php-ext-curl.ini
- Ubuntu/Debian 用户可直接更新：
sudo apt update && sudo apt install ca-certificates - Mac M1 用户常见坑：Homebrew 安装的 PHP 可能读取的是
/opt/homebrew/etc/ca-certificates/cert.pem，需在php.ini中显式设置
某些包死活下不下来，报 Could not parse version constraint 或 file could not be downloaded
这不是网络问题，而是 Composer 尝试解析某个包的 composer.json 时，发现其 version 字段格式非法（比如写了 v1.2.3 而非 1.2.3），或该包 dist ZIP 地址返回了 404（常见于私有包或已删版的包）。此时 Composer 会不断重试，看起来像卡住。
- 定位具体哪个包出问题：加
-vvv后观察最后几行，找类似Downloading https://api.github.com/repos/xxx/yyy/zipball/...的 URL - 手动 curl 测试：
curl -I -L "上面那个 URL"，看是否返回404或403（GitHub 私有库限流） - 临时绕过：删掉
vendor和composer.lock，改用composer update --with-dependencies让 Composer 重新推导依赖树 - 终极手段：在
composer.json中用repositories显式替换问题包为 fork 地址，例如："repositories": [{"type": "vcs", "url": "https://github.com/yourname/package-name"}]
最常被忽略的一点：Composer 的 cache 目录损坏会导致看似网络问题的假象。清缓存不是万能解法，但值得在折腾半天后试一次：composer clear-cache。它不删任何配置，只清掉可能腐烂的 zip 和 json 缓存文件。
