默认使用--prefer-dist并不总更快，因composer自动优选dist或source；强制使用可能因无dist包、镜像延迟、zip扩展缺失等报错或失败。
默认情况下 Composer 就在用 --prefer-dist，手动加它通常不加速，反而可能出问题。
为什么 --prefer-dist 并不总是更快
Composer 会根据包的 dist（压缩包）和 source（Git 仓库）两种来源自动选择安装方式。默认策略是：有稳定版 tag、且平台支持 zip 解压时，优先走 dist；否则退到 source。手动加 --prefer-dist 强制走压缩包，但若包没发布 dist（比如 dev 分支、私有包未配置 dist URL），就会报错 Could not find a matching version of package xxx 或直接 fallback 失败。
-
dist模式依赖 Packagist 提供的预构建 ZIP 包，国内镜像同步延迟时，可能拉不到最新版 -
source模式走 Git clone，适合开发中频繁切分支，但首次克隆慢、占磁盘多 - 网络质量差时，
dist的单个大文件下载反而比多个小 Git 请求更易中断
真正影响安装速度的关键配置
比起硬加 --prefer-dist，以下几项调整见效更明显：
- 换国内镜像源：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（或使用https://mirrors.aliyun.com/composer/） - 启用并行下载：
composer config -g github-protocols https git（避免 HTTPS 协议被限速） - 关闭脚本执行（临时加速）：
composer install --no-scripts --no-autoloader，装完再补composer dump-autoload - 清理旧缓存：
composer clear-cache，尤其当你切过镜像源后，旧缓存可能混用协议导致失败
什么时候必须用 --prefer-dist？
极少数场景下它不可替代：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- CI 环境禁止 Git（如某些容器无 Git 二进制），必须靠
dist安装 - 目标服务器防火墙屏蔽了 Git 端口（9418 / 22），但允许 HTTPS 下载 ZIP
- 你明确知道某包的
dist已发布、且本地缓存损坏，想跳过 source 检查强制重拉
此时应搭配 --no-progress 和 --quiet 减少输出开销，例如：composer install --prefer-dist --no-progress --quiet。
容易被忽略的兼容性坑
--prefer-dist 不是万能开关，它对以下情况完全无效：
- 包的
composer.json中声明了"source": { ... }但没配"dist"字段 → 强制--prefer-dist直接失败 - PHP 版本低于 7.2 且 ZIP 扩展未启用 → 解压失败，报错
ZipArchive::extractTo(): Invalid or uninitialized Zip object - Windows 上路径含中文，某些 ZIP 包解压后文件名乱码 → 自动 fallback 到 source，但不会提示原因
遇到安装卡住或报错，先运行 composer diagnose，再看 composer install -v 的详细日志，重点关注 “Installing xxx (y.z) from dist” 还是 “from source” —— 这才是真实路径，不是命令里写了什么就走什么。
