绝大多数时候该用--prefer-dist，它下载预打包的压缩包，速度快、占用小、校验可靠且不依赖Git；仅当需修改vendor代码调试或开发时才用--prefer-source。
什么时候该用 --prefer-dist？
绝大多数时候就该用它——尤其是部署到线上、跑 CI/CD、构建 Docker 镜像，或者你只是想把项目快速跑起来。--prefer-dist 会让 Composer 优先下载预打包的 .zip 或 .tar.gz 文件（比如从 GitHub Releases 或 Packagist 的 dist URL），解压后直接放进 vendor/。它快、轻、稳。
- 安装速度快：跳过
git clone、检出分支、解析历史等开销 - 磁盘占用小：没有
.git目录、没测试文件、没开发脚本 - 校验可靠：包带 SHA256 签名，下载后自动验证完整性
- 不依赖 Git 可用性：即使服务器没装 Git 或网络屏蔽了 GitHub，只要 dist 地址通就行
常见错误现象：composer install 在 CI 中卡在 Cloning into 'vendor/some/package'... —— 很可能是因为误配了 --prefer-source，而构建机没装 Git 或没配置 SSH key。
什么时候必须用 --prefer-source？
只有当你需要「改 vendor 里的代码」时才真正需要它。比如调试一个底层 bug、临时打补丁、切到某个未发布的 dev-main 分支验证修复，或者正给开源项目提 PR。
- 进
vendor/some/package能直接git log、git checkout feat/x、git diff - 可本地修改并
git commit（注意：下次composer update默认不会保留你的提交） - 配合
"repositories"+"path"类型本地开发时，--prefer-source是刚需——否则无法实时同步你本地源码的变更
性能代价明显：拉一个大包（如 laravel/framework）可能多花几秒甚至十几秒，且每个包额外多占 10–50MB 空间（全是 .git 历史）。
preferred-install 配置怎么写才不翻车？
别全局硬设 "preferred-install": "source"，除非你团队所有人都是包维护者。更安全的做法是按需指定：
{
"config": {
"preferred-install": {
"myorg/*": "source",
"phpunit/phpunit": "source",
"*": "dist"
}
}
}
这样既保证内部包和测试工具始终可调试，又让其他几十个依赖保持轻量。注意两点：
- 通配符
*必须放在最后，否则前面的规则会被覆盖 - 路径匹配是「前缀匹配」，
"monolog/*"会匹配monolog/monolog和monolog/php-handler，但"monolog"不会匹配任何包（缺斜杠）
为什么加了 --prefer-source 有时还是下了 zip？
因为这不是强制指令，而是「偏好」。Composer 会按包的元数据决定是否能照做：
- 如果某包在
composer.json里只写了"dist"信息（没配"source"），那即使你加--prefer-source，也会默默退回到下载压缩包 - 私有 GitLab 仓库若没开放匿名克隆（即没配 public clone URL），Composer 也会 fallback 到 dist
- 可通过
composer show vendor/package查看输出中是否有source : git ...行，来确认该包是否支持 source 安装
最容易被忽略的一点：你改了 composer.json 的 preferred-install，但没删 vendor/ 和 composer.lock，那么下次 install 仍按 lock 文件里记录的方式还原——想彻底切换，得清干净再重装。
