preferred-install 是 composer.json 中控制包拉取方式的配置项，决定默认使用 dist（压缩包）、source（git 克隆）或 auto（动态判断），直接影响 vendor 目录体积、安装速度、.git 存在与否及 ci 构建稳定性。
preferred-install 是什么，为什么会影响你的 vendor 目录
preferred-install 是 composer.json 里的一个配置项，它不控制“能不能装”，而是决定 Composer 默认用哪种方式拉取包：是完整 Git 克隆（source），还是只下 dist 压缩包（dist），或者按包自己声明的默认策略（auto）。它直接影响 vendor/ 目录体积、安装速度、是否带 .git 文件夹，以及 CI 环境能否干净构建。
怎么设才真正生效：全局 vs 项目级，优先级必须搞清
这个配置在三个地方都能写，但优先级从高到低是：项目 composer.json > 当前用户 config.json（composer config --global） > Composer 内置默认（auto）。很多人改了全局配置却没生效，就是因为项目里 composer.json 已有同名字段，直接覆盖了。
- 项目级设置（推荐）：在项目根目录
composer.json的"config"段落里加："preferred-install": "dist" - 全局设置（慎用）：运行
composer config --global preferred-install dist，但团队协作时容易引发不一致 - 临时覆盖：命令行加
--prefer-dist或--prefer-source，比配置项优先级还高
dist 和 source 的实际差异，远不止“有没有 .git”
选 dist 不只是省空间。它意味着 Composer 会去 packagist.org 下载预构建的 zip/tar 包，跳过 Git 克隆和 checkout 步骤；而 source 会 clone 完整仓库，再检出对应 commit —— 这在 CI 环境里可能因网络或权限失败，也会让 vendor/ 多出几百 MB 的 .git 数据。
-
dist：适合大多数生产环境、CI 构建、本地开发（除非你要改依赖源码） -
source：只在你明确需要调试/修改某个包的代码，且该包已用path或vcs类型定义时才必要 -
auto：Composer 根据包是否提供 dist 包、是否有 tag、是否在 packagist 上托管来动态决定——行为不可控，不建议线上用
常见踩坑：PHP 扩展缺失、镜像源失效、私有包不兼容
设成 dist 后突然报错 Failed to download xxx: file could not be downloaded (http 404)？大概率是用了国内镜像源（如阿里云、腾讯云），但镜像没同步某些包的 dist 资源，或该包压根没发布 dist 版本（比如只推了 dev 分支）。
- 检查当前源：
composer config repo.packagist.org.url - 私有 VCS 包（如 gitlab 私仓）默认不走 dist，即使你设了
preferred-install: dist，也要额外配"dist": { "url": "...", "reference": "..." }才生效 - 某些老项目依赖的扩展（如
ext-zip）在解压 dist 包时会报错，php -m | grep zip确认是否启用
最麻烦的是混合场景：团队要求本地开发用 source（方便断点），CI 用 dist（提速），这时别硬靠一个配置打天下，用 composer install --prefer-dist --no-dev 显式控制更稳。