绝大多数时候该用 --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、检出分支、解析历史等开销，实测快 2–5 倍 - 磁盘占用小：没
.git目录、没测试文件、没开发脚本，一个大包能省 10–50MB - 校验可靠：包带 SHA256 签名，下载后自动验证完整性
- 不依赖 Git：服务器没装 Git、网络屏蔽 GitHub、SSH key 没配好？只要 dist 地址通就行
常见错误现象：composer install 在 CI 中卡在 Cloning into 'vendor/some/package'——大概率是误加了 --prefer-source，而构建机根本没装 Git。
什么时候必须用 --prefer-source？
只有当你需要「改 vendor 里的代码」时才真正需要它。比如调试底层 bug、临时打补丁、切到某个未发布的 dev-main 分支验证修复，或者正给开源项目提 PR。
- 进
vendor/some/package能直接git log、git checkout feat/x、git diff - 可本地修改并
git commit（注意：下次composer update默认不会保留你的提交） - 配合
"repositories": [{"type": "path", "url": "../my-local-package"}]时，--prefer-source是刚需——否则报错：Package is not installed as source
性能代价明显：拉 laravel/framework 这类大包可能多花几秒甚至十几秒，且每个包额外多占 10–50MB（全是 .git 历史）。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
preferred-install 配置怎么写才不翻车？
别全局硬设 "preferred-install": "source"，除非你团队所有人都是包维护者。更安全的做法是按需指定：
"config": {
"preferred-install": {
"myorg/*": "source",
"phpunit/phpunit": "source",
"*": "dist"
}
}
- 通配符
*必须放在最后，否则前面的规则会被覆盖 - 路径匹配是「前缀匹配」：
"monolog/*"会匹配monolog/monolog和monolog/php-handler，但"monolog"不会匹配任何包（缺斜杠） -
"preferred-install": { "dev-*": "source", "*": "dist" }这种写法也有效，适合区分开发版和稳定版
为什么加了 --prefer-source 有时还是下了 zip？
因为 --prefer-source 和 --prefer-dist 都是“偏好”，不是强制命令。Composer 会按包实际支持情况自动回退：
- 某包只提供了 dist（比如没配
sourceURL），即使加了--prefer-source，也会退回到下载 zip - 某包禁用了 dist（只允许 source），
--prefer-dist也会失效 - 可用
composer show vendor/package查看该包是否同时支持 dist 和 source
容易被忽略的一点：是否“最新”，跟安装方式无关。dist 对应的是某个 tag 的发布快照，source 克隆的是默认分支（如 main），两者语义不同——一个是稳定交付物，一个是开发主线。
