--prefer-source 不强制所有包走 Git 克隆，仅对声明 source 字段或配置了 vcs 仓库的包生效；Packagist 上仅提供 dist 的包无效，需配合 repositories 配置、dev 分支约束及 clear-cache 才可靠触发源码克隆。
为什么 --prefer-source 有时根本没触发 Git 克隆
很多人执行 composer install --prefer-source 后发现包还是走 dist（zip 下载），根本没 clone。核心原因是：Composer 默认只对「开发依赖」或「启用了 source 仓库类型」的包才考虑源码模式；生产依赖（require）若来源是 Packagist，且该包在 dist 和 source 两者都提供时，Composer 优先选更快的 dist —— --prefer-source 并不强制覆盖所有包。
- 只有当包的
composer.json中明确声明了"source"字段（含type,url,reference），且该字段可用，--prefer-source才会起作用 - 如果包在 Packagist 上只提供了
dist（比如私有包未配置 VCS 信息），加参数也无效 -
composer update比install更容易触发 source 模式，因为 update 会重新解析包元数据
如何确认某个包是否支持 --prefer-source
直接查它的 Packagist 页面或 composer show vendor/package 输出，重点看有没有 source 行：
composer show monolog/monolog # 输出中包含： source : [git] https://github.com/Seldaek/monolog.git 2c1584b6...
若看到类似 source : [git] ...，说明支持；若只有 dist : [zip] ...，那 --prefer-source 对它无效。
- 私有 Git 仓库必须在
composer.json的repositories中显式声明为vcs类型，否则 Composer 不识别其 source 能力 - 用
composer config -g repositories.packagist.org false临时禁用 packagist.org，可迫使 Composer 尝试从你配的 VCS 拉源码（慎用，会影响其他包）
真正强制走 Git Clone 的实操组合
单靠 --prefer-source 不够稳，需配合配置和命令调整：
- 在项目根目录
composer.json中添加仓库声明（以 GitHub 私有库为例）：{ "repositories": [ { "type": "vcs", "url": "https://github.com/your-org/your-package.git" } ] } - 然后运行：
composer require your-org/your-package:dev-main --prefer-source（注意用dev-*分支名，不是^1.0这类稳定版本约束） - 若已安装过，先删掉
vendor/your-org/your-package和composer.lock中对应项，再执行composer update your-org/your-package --prefer-source - 验证是否成功：进
vendor/your-org/your-package目录，运行git remote -v—— 有输出即为 clone 成功；若目录里没有.git，说明仍是 dist 解压
常见报错与绕过方式
遇到 Failed to download ...: Failed to execute git clone，通常不是参数问题，而是环境或权限卡点：
- Git 未安装或不在
$PATH：运行git --version确认；Windows 用户注意 Git Bash 和 CMD 的路径差异 - SSH URL（
git@github.com:...）但没配 SSH key：改用 HTTPS URL，或运行ssh-add ~/.ssh/id_rsa - 公司网络拦截 Git 端口：设置
git config --global url."https://".insteadOf git://，并确保 Composer 使用 HTTPS 协议拉取 - GitHub token 权限不足（尤其私有库）：在
auth.json中配github-oauth或用composer config github-oauth.github.com
最易被忽略的一点：Composer 缓存会记住上次安装方式。哪怕改了 repositories 和参数，旧缓存仍可能复用 dist 包。执行前先运行 composer clear-cache。
