Composer下载中断主因是默认策略（60秒单次超时、仅2次重试）与国内网络不匹配，需通过composer config -g repos.packagist验证镜像是否生效（输出应为镜像URL而非packagist.org），并用curl -I手动测试镜像连通性，同时排查项目级repositories覆盖、DNS解析、TLS握手等底层问题。
Composer 下载中断不是“网断了”，而是默认策略和国内网络环境严重不匹配——它卡在 DNS 解析、TLS 握手或 CDN 缓存污染上，却只给 60 秒单次超时、2 次重试，根本等不到响应。
怎么确认是不是镜像源没生效
很多人执行 composer config -g repo.packagist 后就以为搞定了，但实际请求可能还在连 packagist.org。关键看两处：
- 运行
composer config -g repos.packagist，输出必须是类似{"type": "composer", "url": "https://mirrors.tuna.tsinghua.edu.cn/composer/"}，而不是packagist.org - 手动测镜像是否通：
curl -I https://mirrors.tuna.tsinghua.edu.cn/composer/packages.json，要能秒回HTTP/2 200；如果超时或返回 404，问题不在 Composer 配置，而在本地 DNS、代理或防火墙 - 检查项目根目录下
composer.json是否硬编码了"repositories"字段——它会覆盖全局配置，得删或改掉
为什么加了 --retries=5 还失败
Composer 的重试机制只对 HTTP 层有效，但很多“下载中断”根本没走到 HTTP 请求阶段：
- DNS 解析卡住（比如用 114.114.114.114 在某些地区返回错误 IP），
--retries完全无效 - TLS 握手失败（PHP 版本
- 中间代理劫持或 CDN 缓存污染，导致下载的 ZIP 校验失败（
dist.sha256不匹配），报错是file could not be downloaded，但本质不是没下完，是下错了 - 真正起效的是组合：环境变量
COMPOSER_NETWORK_TIMEOUT=300+ 命令行--retries=5+--prefer-dist，三者缺一不可
vendor 目录损坏后怎么安全清理
下载中断最常留下半截 vendor/ 和截断的 vendor/composer/installed.json，强行重试只会让状态更乱：
- 先删干净：
rm -rf vendor（Linux/macOS）或rmdir /s vendor（Windows） - 再清缓存：
composer clear-cache，否则可能复用损坏的 ZIP 包 - 别只删
composer.lock—— 如果 lock 文件本身是旧版生成的，跟新镜像元数据不兼容，反而引发依赖解析失败 - 推荐命令组合：
rm -rf vendor && composer clear-cache && composer install --no-plugins --prefer-dist
CI/CD 环境里反复失败怎么稳住
CI 容器每次都是全新环境、无缓存、DNS 策略严、内存受限，而 Composer 默认配置完全没考虑这点：
- 必须开启缓存：GitHub Actions 写
cache: $HOME/.composer/cache，GitLab CI 对应配cache关键字，否则每次重下百 MB ZIP 是常态 - 强制走 dist：
--prefer-dist跳过 git clone，避免触发 GitHub API 限流（尤其没配github-oauth时） - 禁用插件：
--no-plugins防止hirak/prestissimo类插件并发下载却校验失序，引发校验失败 - 别信
process-timeout—— 它管不了 HTTP 连接，CI 中真正要设的是COMPOSER_NETWORK_TIMEOUT=300和--retries=5
最容易被忽略的是：某些包（如 "monolog/monolog": "dev-main"）会绕过 Packagist 镜像，直连 GitHub 下 ZIP，此时换镜像完全无效，得单独配 github-oauth 或改用稳定 tag。
