--prefer-dist 本身无容错，需配合 --retries=5、--timeout=600 和镜像源协同才有效；失效主因是 dist.url 缺失或非 https、私有包未发 release、镜像未生效或缓存损坏。
--prefer-dist 本身不提供容错机制，它只是让 Composer 优先走 ZIP/TAR 包下载路径；真正的容错靠的是 HTTP 层重试 + 超时调优 + 镜像源协同，三者缺一不可。
为什么加了 --prefer-dist 还会失败
常见错误现象：CI 日志里仍出现 Cloning into 'vendor/monolog/monolog' 或卡在 Downloading (0%)；或者报 cURL error 28: Operation timed out。
-
--prefer-dist不是强制开关，而是“有 dist 就用，没有就 fallback 到 source”——而 fallback 后的git clone完全不受--retries控制 - 私有包没打 GitHub Release、
composer.json里写了"dev-main"、或composer.lock记录的是 source 模式，都会导致 dist 失效 - 镜像源没切成功（比如项目级
repositories覆盖了全局配置），--prefer-dist就会去海外拉 source，直接变慢+易超时
必须配合的三个关键参数
单独加 --prefer-dist 在弱网下基本等于白加。真正起作用的是这组组合：
-
--retries=5：仅 Composer 2.2+ 有效，只对 HTTP 下载生效（dist 包），默认是 3 次 -
--timeout=600：覆盖默认 300 秒，防止单次请求被 NAT 或 TLS 握手卡死 -
--no-interaction --no-progress：避免进度条刷新干扰日志，也减少终端 I/O 延迟
推荐 CI 脚本写法：composer install --prefer-dist --retries=5 --timeout=600 --no-interaction --no-progress --optimize-autoloader --no-dev
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
容易被忽略的底层依赖项
很多团队调了参数还失败，问题出在链路层：
-
dist.url必须是 HTTPS，不能是git@github.com:这类 SSH 格式——否则 Composer 会静默 fallback - 构建机 DNS 解析慢？加
CURL_IPRESOLVE=4强制 IPv4，避开某些 ISP 的 IPv6 不稳定 - 缓存目录残留损坏 ZIP？
rm -rf ~/.composer/cache/files/vendorname/*比单纯重试更可靠 - 别信
--no-cache：它跳过已缓存包，但不清理半途失败的临时文件，下次仍校验失败
离线或弱网环境下的兜底验证
当网络彻底不可靠时，--prefer-dist 已无意义，得换思路：
- 先用
composer install --no-install校验本地vendor/是否与composer.lock一致（不联网） - 再跑
composer show --installed看实际装了哪些包，人工比对composer.lock中的packages列表 - 若需防篡改，手动校验
vendor/composer/installed.json里的dist.shasum字段是否匹配 lock 文件
最常被忽略的一点：dist 模式失效往往不是参数没加对，而是 dist.url 根本没生成出来——查 composer show -s vendor/package 输出里 dist 字段是否非空且为 HTTPS 链接，比反复改命令行更直接。
