默认走dist，仅需修改vendor代码、调试或打patch时才用source；确认方式：查vendor目录有无.git，或运行composer show包名-f=source看字段值。

默认走 dist，只有真要改 vendor 里的代码、切分支、打 patch 或调试时，才该用 source。 其他情况强行开 --prefer-source，大概率在 CI 卡住、构建变慢、磁盘暴涨，还可能让本地修改被下次 composer update 覆盖掉。

怎么确认当前装的是 source 还是 dist

别猜，直接看文件系统或命令输出：

• 进 vendor/some/package，执行 ls -a | grep git —— 有 .git 目录就是 source
• 运行 composer show some/package -f=source，输出中 source 字段为 vcs 表示走 Git 克隆，dist 表示走压缩包
• composer show 不依赖当前 vendor 状态，比手动翻目录更可靠；而 ls -a 能快速验证是否真有工作区

什么时候必须用 --prefer-source

不是“想用就用”，而是遇到这些具体场景才绕不开：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

• 你在本地开发一个私有包，并通过 "repositories": {"type": "path", "url": "../my-package"} 引入 —— 不设 --prefer-source 或 "preferred-install": {"my/package": "source"}，改了源码不会实时生效
• 要给 monolog/monolog 提 PR，需切到 main 分支并加 var_dump 调试 —— 必须 composer require monolog/monolog:dev-main --prefer-source
• 某包只发布了 dev-master，没打任何 tag，Packagist 上压根没 dist 包 —— 加了 --prefer-dist 也会自动 fallback 到 source
• 用 xdebug 断点进函数内部，但 dist 解压后没 .git，断点行号和实际代码对不上 —— source 才能保证调试位置准确

为什么 --prefer-dist 是默认，但开发时别盲目依赖它

--prefer-dist 的“快”是有代价的，而且这个代价在开发阶段会反向咬人：

• composer install --prefer-dist 不会覆盖已存在的 source 安装 —— 得先删掉 vendor 再装，否则你以为切回 dist，其实还是老的 git 克隆体
• 某些企业镜像（比如腾讯云 TKE 镜像）只缓存 dist，你加了 --prefer-source 就会绕过镜像直连 GitHub，可能被墙或超时
• composer update 时，如果新版本约束匹配某个已发布的 tag（如 ^2.10），即使之前是 source 安装，Composer 也可能悄悄切回 dist，导致你加的调试代码消失
• source 安装后你确实可以 git commit 本地 patch，但下次 composer update 会按 composer.lock 中锁定的 commit hash 重新检出 —— 除非你手动 git push 到自己的 fork 并改 repositories，否则提交会被覆盖

配置优先级和常见踩坑点

参数、项目配置、全局配置之间有明确优先级，写错位置或格式就全项目翻车：

• 优先级：命令行参数 > 项目 composer.json 的 config.preferred-install > 全局 composer config --global preferred-install
• "preferred-install": {"monolog": "source"} 是错的 —— 匹配基于包名前缀，"monolog" 不匹配 monolog/monolog，得写成 "monolog/" 或 "monolog/*"
• 全局设 "preferred-install": "source" 是高危操作：所有人本地 vendor 都多出几十 MB .git 目录，CI 构建变慢，还可能因 Git 配置不一致报错
• 配置生效需重跑 composer install 或 composer update，已有 vendor 不会自动重装 —— 这点最容易被忽略

最常被忽略的一点：--prefer-source 和 --prefer-dist 都只是“偏好”，不是强制开关。Composer 会按包实际支持情况自动降级：你加了 --prefer-source，但对方包没配 source 地址，照样下 dist；反过来也一样。所以查 composer show 比看命令更可靠。