--prefer-dist 能绕过网络抖动，因其强制通过单次 HTTPS 下载预构建 zip 包，避免 git clone 的多环节连接中断；但私有库未开启 archive、配置 prefer-source 优先或调试未发布分支时会失效。
直接重试 composer install 很可能失败，真正该做的是换下载策略 + 调整网络配置，而不是反复点回车。
为什么 --prefer-dist 能绕过网络抖动？
Composer 默认对有 Git 标签的包会尝试 git clone，但这个过程涉及多次 TCP 连接、SSH 认证、浅克隆协商，任意一环被中断（比如运营商 NAT 超时）就会卡死或报错；而 --prefer-dist 强制走单次 HTTPS 下载预构建 zip 包，校验快、无状态、失败后重试成本低。
- 它不强制生效——只在包提供
distURL 时才用（绝大多数 Packagist 上的稳定版都提供） - 对
dev-master、dev-feature/x或path类型仓库无效，加了也自动 fallback 到 source - CI/CD 或生产部署中，它还能避免因缺失 SSH key 或 Git 配置导致的静默失败
哪些场景下 --prefer-dist 反而会出错？
不是所有项目都适合无脑加这个参数。常见翻车点：
- 私有 GitLab/GitHub 私库没开启 archive 功能，
distURL 返回 404 → Composer 报Could not find a matching version of package xxx - 项目里已存在
"config": {"prefer-source": true}，它会覆盖--prefer-dist，必须手动删掉 - 你正在调试某个依赖的未发布分支，需要改源码 → 此时必须用
--prefer-source，否则 vendor 里没有.git目录
比加参数更关键的是调通底层网络
光靠 --prefer-dist 只能缓解，不能根治。卡在 Downloading (0%) 或反复断连，90% 是 cURL 层超时太短或连接被中间设备切断：
- 全局延长超时：运行
composer config -g repos.packagist.org {"url": "https://packagist.org", "type": "composer", "options": {"http": {"timeout": 600, "max_redirects": 20}}} - 确认镜像可用：执行
curl -I https://mirrors.aliyun.com/composer/，返回非 200 就换源（推荐腾讯云https://mirrors.cloud.tencent.com/composer/） - 若本地有代理，设
https_proxy=socks5h://127.0.0.1:1080比 Composer 内置 proxy 更稳 - 检查 PHP 的 cURL 是否信任证书：
php -r "print_r(curl_version());"看ssl_version和features，若CURL_VERSION_SSL缺失或curl.cainfo指向空文件，就得重装 OpenSSL 或更新 CA bundle
安装中断后别硬等重试，先看错误类型再清理
重试是否有效，取决于失败阶段：
- 报
Failed to extract vendor/package-name: unable to open archive→ zip 文件损坏，删vendor/+composer clear-cache再跑 - 报
Invalid argument supplied for foreach()→vendor/composer/installed.json被截断，删vendor/即可（不用单独删 json） - 报
The zip extension and unzip command are both missing→ 实际是上一步解压失败，不是缺扩展，别装 zip 扩展，先清缓存 - 什么错误都没输出，进度条不动 → 加
-vvv看最后卡在哪条 URL，大概率是 GitHub API 或镜像站响应异常
最常被忽略的一点：Composer 的“断点续传”只对成功解压过的包跳过，但一旦 zip 校验失败，它不会重用已下载的残片——所以清理缓存不是多此一举，而是必要步骤。
