--prefer-source 仅在需修改依赖源码、调试进函数或依赖仅存于 Git 分支时有用；它强制克隆仓库保留 .git，但更慢、更占磁盘且依赖 Git 配置，CI/CD 中需慎用。
什么时候 composer install --prefer-source 真的有用？
只有当你需要修改依赖包源码、调试进函数内部、或依赖尚未发布正式版本（比如只在 Git 分支上）时，--prefer-source 才有实际价值。它强制 Composer 克隆 Git 仓库而非下载 Zip 包，因此你会得到完整的 .git 目录和所有分支/标签信息。
常见误用场景：以为它能“加快安装”或“避免权限问题”——其实相反，克隆比下载 Zip 更慢、更占磁盘，且要求系统已配置好 Git 并能访问对应仓库（比如私有 GitLab 需提前配好 SSH key）。
- 你正在为某个包提交 PR，需本地改代码 +
git commit+git push - 你在调试一个第三方包的 bug，想加
var_dump或断点，且不希望每次更新都丢失修改 - 你依赖的是
"monolog/monolog": "dev-main"这类开发分支，而该分支尚未打任何 tag，Zip 包不可用
--prefer-source 和 --prefer-dist 的行为差异
默认情况下 Composer 优先用 --prefer-dist：从 Packagist 缓存的 Zip 包安装，速度快、离线可用、不依赖 Git。启用 --prefer-source 后，Composer 会：
- 检查包的
source字段（即repositories中定义的 VCS 地址），跳过dist字段 - 执行
git clone --no-checkout <url></url>，再git checkout -qf <commit-hash></commit-hash> - 保留完整 Git 历史，
vendor/<vendor>/<package>/.git</package></vendor>可用
注意：如果包未声明 source（比如纯 ZIP 发布、或被设置为 "dist": {"type": "zip", ...} 且无 source），--prefer-source 会直接失败并报错：Source not found for package xxx。
CI/CD 环境下慎用 --prefer-source
在 GitHub Actions、GitLab CI 等环境中，默认 runner 不带 SSH key，也未必预装 Git（某些精简镜像如 php:alpine 需手动 apk add git）。此时启用 --prefer-source 极易失败：
- 遇到私有包时，
git clone git@gitlab.example.com:xxx因无 key 被拒绝 - 使用 HTTPS 地址时，若包配置了
"source": {"url": "https://..."}但未设"options": {"http": {...}}，可能因无凭据 401 - 克隆过程比下载 Zip 多出数秒到数十秒，拖慢构建时间，且无法利用 CDN 缓存
解决方案不是硬扛，而是明确指定策略：在 composer.json 里用 "config": {"preferred-install": {"my-private-package": "source"}}，只对特定包启用源码安装，其余保持 dist。
如何验证当前安装方式？
最直接的方法是看 vendor/<vendor>/<package></package></vendor> 目录下有没有 .git 文件夹。但更可靠的是查 Composer 的锁文件：
cat composer.lock | jq -r '.packages[] | select(.name == "symfony/console") | .source.type'
输出 git 表示用了源码安装，zip 或 tar 表示用了 dist。注意：这个值由安装时的选项决定，后续 composer update 若没加 --prefer-source，可能变成 dist —— 它不会自动继承。
真正容易被忽略的是：一旦你用 --prefer-source 装过，又没删 vendor 和 composer.lock，下次即使不加参数，只要 lock 文件里记录的是 source 类型，Composer 仍会走源码路径。所以别只看命令，要看 lock 文件的实际记录。
