--prefer-dist 优先下载压缩包，速度快、开销小；--prefer-source 强制克隆完整仓库，适合调试。Composer 默认自动选择，但受包配置、lock 文件、环境变量等影响，需显式指定或配置 preferred-install 确保生效。
什么是 --prefer-dist 和 --prefer-source
--prefer-dist 告诉 Composer 优先从包的 发布版本（dist） 下载，通常是压缩包（如 .tar.gz 或 .zip），由 Packagist 缓存并分发；--prefer-source 则强制克隆源码仓库（如 Git），适合需要修改包代码或调试时使用。
大型包（比如 laravel/framework、symfony/symfony）含大量历史提交和开发分支，--prefer-source 会完整 clone 整个仓库，耗时长、占磁盘多；而 --prefer-dist 只下载当前版本的精简归档，解压快、网络开销小、IO 压力低。
为什么默认不总是用 --prefer-dist
Composer 默认行为是「自动选择」：多数情况下选 dist，但某些条件会回退到 source，例如：
- 包未配置
dist信息（如私有仓库未打 tag 或未配置archive） - 本地
composer.json中该包被设为"dev-master"或其他开发版约束，且未提供 dist URL - 启用了
COMPOSER_PREFER_SOURCE=1环境变量 - 运行了
composer install但composer.lock记录的是 source 安装方式（可能源于之前手动加了--prefer-source）
所以不能只靠“默认”，得显式控制。
如何确保大型包走 --prefer-dist
最直接有效的方式是在安装/更新命令中加参数：
composer install --prefer-dist composer update --prefer-dist composer require monolog/monolog --prefer-dist
若想全局生效（推荐 CI/CD 或团队统一环境）：
- 在项目根目录写
composer.json，添加："config": { "preferred-install": "dist" } - 或全局设置（影响所有项目）：
composer config -g preferred-install dist
注意："preferred-install" 支持通配符，比如 "*": "dist"、"vendor/*": "dist"，但对大型包，直接设 "*": "dist" 最稳妥。
常见失效场景与排查方法
即使写了 --prefer-dist，仍可能走 source，典型原因：
- 包本身没提供 dist —— 查看
composer show vendor/package输出，若dist字段为空或显示type: git，说明没 dist 发布 -
composer.lock已锁定为 source 方式 —— 删除composer.lock和vendor/后重试 - 用了
repositories自定义源，但未正确配置distURL 或archive模板 - 运行
composer update vendor/package时，该包在composer.lock中记录为 source，且未加--prefer-dist，Composer 会复用旧方式
验证是否成功：安装后进 vendor/vendor-name/package/，执行 ls -la。如果看到 .git 目录，说明走了 source；没看到且有 composer.json + 正常代码文件，基本就是 dist。
真正影响速度的不是参数名本身，而是 dist 包是否真实存在、能否被命中。很多团队卡在“以为加了就生效”，其实漏查了 lock 文件或私有源配置 —— 这点比记住命令更重要。
