prefer-source 是让 Composer 从 VCS 克隆源码而非下载压缩包的配置，用于调试、打补丁或使用未发版的 dev 分支；可临时（命令行参数）、项目级（composer.json）或全局（--global）启用，但需注意私有仓库权限、CI 性能及 .git 清理问题。
prefer-source 是什么，什么时候必须用它
它不是强制下载源码的开关，而是告诉 composer install 或 composer update：「如果包提供了 VCS 仓库（比如 GitHub），就直接 clone 源码，别下 zip 包」。默认行为是下 dist（压缩包），速度快、缓存友好；但你改代码、打 patch、看 commit 历史、或包没发布新 tag 却需要最新 dev 分支时，就得切到 source 模式。
全局启用 prefer-source 的两种写法
最常用的是改配置项，不是加参数。很多人误以为 composer install --prefer-source 能永久生效，其实它只对当次命令有效，且不会影响后续 composer update —— 因为 Composer 默认会把已安装的包按原方式复用（dist 或 source），除非显式要求刷新。
- 临时生效（仅本次命令）：
composer install --prefer-source或composer update --prefer-source - 永久生效（项目级）：在
composer.json根对象里加"config": { "prefer-source": true } - 永久生效（全局）：运行
composer config --global prefer-source true，影响所有后续项目
prefer-source 和 --dev / --no-dev 的关系
它们互不干扰。--dev 控制是否安装 require-dev 下的包；prefer-source 控制「怎么装」——哪怕只装生产依赖，只要开了 prefer-source，monolog/monolog 这类包照样会 git clone。但要注意：有些私有包没开 public Git 访问，或公司防火墙屏蔽 git:// 协议，这时 prefer-source 会卡在 Cloning into 'xxx'... 并报错 fatal: Could not read from remote repository.。
- 常见错误现象：
Failed to download vendor/package: Failed to execute git clone --no-checkout ... - 排查路径：先确认该包的
source字段是否在 packagist.org 上可见（点进包页 → 「Source」tab） - 若用私有 Packagist（如 Satis），需确保其
repositories配置中 type 是composer且支持 source 同步
源码模式下 vendor 目录变大的真实代价
一个 symfony/console dist 包约 150KB，source 模式下带完整 .git 目录可能超 10MB。CI 构建时如果每次都 --prefer-source，拉取时间、磁盘占用、缓存失效概率都会明显上升。更隐蔽的问题是：某些部署脚本会递归删除 .git，结果导致下次 composer update 失败 —— 因为 Composer 检测到目录里有 .git，就认定这是 source 模式安装的，但 .git 又被删了，校验失败。
- CI 场景建议：一律用 dist（默认），除非调试需要；可用
composer install --no-dev --optimize-autoloader配合缓存加速 - 开发机可开 prefer-source，但记得定期
git clean -xffd vendor/清理残留 .git（慎用，先备份） - 不要在
composer.json里长期开着"prefer-source": true提交到主分支，尤其团队协作时
真正难处理的不是怎么开 prefer-source，而是它和私有仓库权限、CI 网络策略、部署清理逻辑混在一起时，错误信息往往只报「clone 失败」，实际得一层层查 SSH key、HTTPS token、git config url 重写规则。
