—prefer-dist是带fallback的优先策略，非强制开关；它优先下载packagist声明的dist归档（含校验值），若不可用则自动回退source，不报错、不中断，仅通过-v日志中“downloading”或“cloning”可识别实际路径。
—prefer-dist 不是开关，而是带 fallback 的优先策略
--prefer-dist 告诉 Composer：“如果这个包在 Packagist 上声明了 dist 字段（含 ZIP/TAR 下载地址和 SHA256 校验值），就优先用它；如果没有，别硬来，自动切回 --prefer-source 行为。”它不会报错，也不会中断安装，你几乎感知不到 fallback 发生——除非看 -v 日志里出现 Cloning 而不是 Downloading。
这意味着：
- 加了
--prefer-dist≠ 一定走 dist：dev 分支、私有仓库未启用 archive、"type": "path"等场景下，它直接失效 - 不加也不代表走 source：Composer 2.2+ 默认对稳定 tag 就倾向 dist，除非你之前设过
preferred-install: source或启用了COMPOSER_PREFER_SOURCE=1 -
composer.lock里记录的是上次实际安装方式，下次install会默认复用——所以旧 lock 文件可能锁住 source 路径，导致新加--prefer-dist也无效
什么时候加 --prefer-dist 真正起效且必要
它只在特定约束环境下才从“可选”变成“必须”：
- CI/CD 流水线中：避免反复 clone 同一仓库，绕过 Git 认证、SSH key、网络超时等问题
-
Docker 构建阶段：基础镜像通常没装 Git，或容器内无 GitHub token，
--prefer-dist是唯一能完成安装的方式 -
只读文件系统部署（如某些 PaaS）：source 方式需要写
.git目录，直接失败 - 本地首次安装大型项目（如 Laravel + 多 SDK），且所有依赖都打了正式 tag：能跳过 git clone + checkout + .git 清理，明显缩短 vendor 解压前等待时间
反例："guzzlehttp/guzzle": "dev-patch-abc#commit-hash" 这种开发版约束，根本没 dist 可用，加了也白搭。
—prefer-dist 的性能优势和隐藏成本
优势很实在：
- 下载体积小：dist 包不含
.git、测试文件、文档、历史提交，symfony/symfony的 dist 比完整 clone 小 80%+ - 速度快：单次 HTTP GET + 解压，不依赖本地 Git、不触发浅克隆逻辑、不受 GitHub API 限速影响
- 稳定：CDN 缓存友好，镜像站（如阿里云）分发的 dist 包直连快、重试少
但容易被忽略的点：
- 它依赖镜像站缓存 dist 包：私有包若只提供 Git 地址、没发布 ZIP，
--prefer-dist会静默 fallback，但若同时启用了COMPOSER_DISABLE_NETWORK=1（离线安装），就会直接报错 - 无法调试 vendor 代码：dist 安装后没有
.git，改了代码也无法git diff或提 PR；想 patch 必须切到--prefer-source或手动 fork - 并发下载数不提升速度：新版 Composer 已弃用
parallel-downloads，要提速得配http-max-concurrent-downloads，且值别超过 12
如何确认当前是否真走 dist 流程
最可靠的方法是加 -v 运行：
composer install -v --prefer-dist
观察日志中是否出现类似：
Downloading <code>monolog/monolog</code> 2.12.0 (https://api.github.com/repos/monolog/monolog/zipball/2.12.0)
如果看到：
Cloning <code>https://github.com/monolog/monolog.git</code>
说明 fallback 到了 source。此时应检查：
- 该包是否为 dev 版本（如
dev-master） - 项目
composer.json中是否有"prefer-source": true或"preferred-install": "source" - 是否误设了全局
preferred-install：运行composer config --global --list | grep preferred-install - 私有仓库是否配置了
dist字段（GitLab 需开启 Archive 功能，GitHub Release 需打 tag）
真正影响速度的，从来不只是参数本身——而是 dist 包是否存在、镜像源是否可用、你的机器能否稳定连接 CDN 节点。--prefer-dist 只是把“快的路径”暴露出来，前提是你得先把它配对。
