执行 composer install --prefer-source 时，Composer 会从 Git 等 VCS 克隆完整源码仓库而非 ZIP 包，适用于调试、打补丁或查历史；但仅当包声明 source 信息时生效，否则退回到 dist 模式。
直接结论：执行 composer install --prefer-source 时，Composer 会从 Git（或其他 VCS）克隆包的完整源码仓库，而不是下载预构建的 ZIP 包。这适用于需要调试、打补丁或查看历史提交的场景。
为什么 --prefer-source 会拉取 Git 仓库而非 ZIP
Composer 默认优先使用 dist（即打包好的 ZIP/TAR），因为更快、更轻量；但启用 --prefer-source 后，它会查找包的 source 信息（通常在 composer.json 的 source 字段或 Packagist 元数据中），并调用 git clone（或 hg clone/svn checkout）拉取完整历史。
- 只有包明确声明了
source（含type、url、reference）才会走源码模式 - 若包未提供
source（例如某些私有 ZIP-only 包），--prefer-source会退回到dist并静默忽略该标记 - 本地已存在
vendor/{vendor}/{package}且是 Git 仓库时，composer install默认会git checkout到锁定版本，无需重 clone
composer install 和 composer update 对 --prefer-source 的处理差异
两者都支持该参数，但行为略有不同：
-
composer install：严格按composer.lock中记录的source.reference执行git checkout，不更新远程分支 -
composer update：先 fetch 远程 origin，再 checkout；若远程reference已失效（如 commit 被 force-push 删除），会报错Failed to execute git checkout ... - 若想强制刷新所有源码包（比如切换了镜像或修复了网络），可加
--force-reinstall配合--prefer-source
常见问题与避坑点
实际使用中容易卡在这里：
- 公司内网无 Git 端口（如屏蔽了 9418 或 22）→ 改用 HTTPS Git URL（需在
composer.json中配置repositories替换源） - SSH 密钥未配置或权限不足 → 报错
Permission denied (publickey)，此时应改用 HTTPS 源或运行ssh-add - 某些包的
source.url指向私有 GitLab/Gitee，但未配置auth.json→ 触发 401，需提前写入 token -
vendor下出现.git目录但无法git status→ 可能是浅克隆（shallow clone），Composer 默认启用--depth=1，如需完整历史，得配"options": {"github-protocols": ["https"]}并禁用 shallow（需自定义 installer）
真正要改源码或查 blame 时，--prefer-source 是必要条件；但别默认全局开启——它会让 vendor 体积变大、安装变慢、CI 缓存失效更频繁。是否启用，得看当前任务要不要碰 Git 本身。
