--prefer-dist下载预构建压缩包，--prefer-source执行git clone获取完整Git仓库；前者为发布快照，后者支持分支切换、commit查看及PR提交；指定dev分支或commit hash时必须用--prefer-source，否则失败或降级。
prefer-dist 和 prefer-source 的本质差异
它们不是“快 vs 慢”或“旧 vs 新”的选择，而是两种完全不同的交付形态：--prefer-dist 下载预构建的压缩包（zip/tar），--prefer-source 执行 git clone 获取源码仓库。前者拿到的是带版本号的发布快照，后者拿到的是可切换分支、查看 commit 历史、直接修改并提交 PR 的完整 Git 工作目录。
什么时候必须用 --prefer-source
当你依赖一个未打 tag 的开发状态时，--prefer-source 不是可选项，而是必要条件：
- 指定
dev-main、dev-feature/x这类开发分支时，Composer 默认拒绝走 dist —— 因为 dist 只绑定 tag - 用 commit hash 安装（如
monolog/monolog:dev-main#7f8a1c2），不加--prefer-source会报Source not found或静默降级到 latest stable - 需要在
vendor/里直接改代码、调试、打 patch 并向原仓库提 PR
验证是否生效：装完立刻进 vendor/package/.git，运行 git rev-parse HEAD 看是不是你指定的 commit。
为什么 --prefer-source 有时没 clone 成功
常见失败不是参数写错，而是包本身不支持 source 安装：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
composer show -s vendor/package输出里没有source行 → 包的composer.json没声明"source"字段 - 私有仓库（如 GitLab）没在
repositories中明确定义为"type": "vcs"，Composer 就不会尝试 clone - 包只通过 Packagist 发布 dist（如多数 Laravel 官方包），强行加
--prefer-source会静默 fallback，不报错也不 clone
注意：--prefer-source 对纯 dist 发布的包无效，它不会“变出”一个不存在的 Git 仓库。
别设全局 prefer-dist / prefer-source
用 composer config --global prefer-dist true 这类全局配置是危险操作：
- 不同包对 dist/source 的支持程度差异极大 —— 某个私有包只提供 source，另一个只发 zip，全局强制会直接中断安装
- CI/CD 流水线里混用 dev 分支和 stable 版本时，全局设置会让行为不可预测
- 真正可控的方式是写进
composer.json的"preferred-install"字段，按包名或模式精细控制，例如："preferred-install": { "dev-*": "source", "*": "dist" }
实际项目里，大部分包走 dist，少数需要调试的包显式 require 加 --prefer-source，才是稳定又灵活的做法。
