Composer默认仅对单次HTTP请求重试3次，但不重试整个下载流程；process-timeout超时或Content-Length mismatch错误会直接退出，--retry仅对HTTP下载失败生效，需配合clear-cache和延长timeout才有效。
composer install/update 为什么没自动重试
Composer 默认对单次 HTTP 请求会重试最多 3 次（由 cURL 底层控制），但对整个包下载流程（比如 git clone、解压、校验）不自动重试。一旦 process-timeout 触发中断，或 Content-Length mismatch 报错，就直接退出——它不会回退重试那个包，而是整个命令失败。
--retry 参数只在特定场景生效
--retry 不是全局开关，它只作用于「HTTP 下载失败」这一环，且仅限 install 和 update 命令。常见有效场景包括：
- 服务器返回 502/503 或连接被代理切断，cURL 报
Failed to open stream - 镜像源瞬时不可用，但几秒后恢复
- 你明确加了
--retry=3，且失败发生在 dist ZIP 下载阶段（不是 git clone）
无效场景：
-
git clone卡住（需单独配 Git 超时，如git config --global core.sshCommand "timeout 300 ssh"） - 缓存文件已损坏（
Content-Length mismatch），重试只会反复读坏文件 - 依赖解析阶段报错（如
Root package cannot be resolved），--retry完全不介入
真正可控的重试组合：--retry + clear-cache + timeout
单靠 --retry 解决不了多数国内用户的真实问题。必须搭配以下三步才稳定：
- 先运行
composer clear-cache—— 清掉~/.composer/cache/files/下所有可能损坏的 ZIP - 设长超时：
composer config -g process-timeout 1800（避免git clone或大包解压中途被杀） - 再执行
composer install --retry=3 --no-cache（--no-cache强制跳过本地缓存，从头下载）
注意：--no-cache 和 --retry 可共存，但 --no-cache 会让每次重试都走完整网络请求，适合排查缓存污染；日常使用建议先清缓存，再正常 --retry。
CI 环境里别依赖 --retry 靠运气
GitHub Actions、GitLab CI 或 Jenkins 中，--retry 很容易掩盖真实问题。更健壮的做法是：
- 显式配置镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 禁用 HTTPS 校验（仅限内网可信环境）：
composer config -g secure-http false - 加内存限制：
COMPOSER_MEMORY_LIMIT=-1，防止依赖解析 OOM 后假死 - 固定并发数：
composer config -g http-max-concurrent-downloads 8，避免并发过高触发系统级限制
重试逻辑越简单越好——与其让 CI 反复跑 --retry=5，不如确保第一次就成功。缓存损坏、DNS 解析失败、证书链过期这三类问题，--retry 一概无能为力。
