prefer-dist 是 Composer 默认启用的安装策略，优先下载压缩包（dist）而非克隆源码仓库（source），以提升速度与稳定性；仅当 dist 不可用时才回退到 source。
prefer-dist 是什么，为什么默认开启
prefer-dist 是 Composer 的一个安装策略开关，控制它从哪里获取包：压缩包（dist）还是源码仓库（source）。默认启用时，Composer 会优先找 dist 类型的发布包（比如 GitHub 的 zip 或 tar.gz），而不是克隆 Git 仓库。
这背后是性能和稳定性的权衡：下载压缩包比 git clone 快得多，尤其对大项目或 CI 环境；而且 dist 包经过打包校验，版本更确定，不会受分支变动、未 push 提交影响。
但注意：prefer-dist 不是“只用 dist”，而是在 dist 可用时跳过 source。如果某个包没提供 dist（比如私有仓库没配 dist URL），Composer 会自动 fallback 到 source。
什么时候该关掉 prefer-dist
关闭 prefer-dist（即启用 prefer-source）只在少数真实场景下有必要：
- 你在本地开发一个依赖包，想直接改它的源码并实时看到效果——这时需要
git clone出来，而不是解压一份静态快照 - 某个包的 dist 包缺失关键文件（比如漏了
tests/或bin/目录），而你又必须用到这些内容 - 你用的是 fork 后未打 tag 的分支，而该 fork 没配置 dist 链接，Composer 找不到对应压缩包，只能退到 source
关法很简单，在项目根目录运行：
composer config prefer-source true或者手动编辑
composer.json 加一行："config": { "prefer-source": true }。注意：二者互斥，设了 prefer-source 就自动覆盖 prefer-dist。
如何确认当前生效的是 dist 还是 source
最直接的办法是看 vendor/ 下包的结构：dist 包解压后没有 .git 目录；source 包则完整包含 .git，且 composer show vendor/package 输出里会显示 source 字样。
另一个可靠方式是加 verbose 参数重装一次：
composer install -v。过程中你会看到类似这样的日志：
- Downloading vendor/package (1.2.3)表示用了 dist；如果是：
- Installing vendor/package (1.2.3): Cloning abcdefg from cache，那就是 source。
别只看 composer.lock 里的 dist 字段——它只是记录当时用的分发方式，不反映当前实际安装行为。真正起作用的是 config 设置 + 包自身是否提供 dist 元信息。
私有包或 GitLab/Gitee 上的包容易踩的坑
私有仓库默认不带 dist 信息，即使你开了下载 ZIP 功能，Composer 也未必能自动发现。常见错误现象是：明明写了 "type": "package" 或配置了 VCS repository，却始终 fallback 到 source，还报 Failed to download vendor/private: No releases available。
- 确保 Git 仓库打了 tag（
git tag v1.0.0），且 tag 名符合 Composer 版本规则（如不能是1.0.0-rc而没写stability） - 如果用
package类型手动定义，必须显式提供dist字段，URL 指向可公开访问的 zip 包，且含"type": "zip"和有效"reference" - Gitee/GitLab 自建实例需开启
archive支持，并在composer.json的 repository 配置中指定"dist": { "url": "...", "type": "zip" }
dist 的 URL 必须能被 Composer 直接 GET 到，不能是登录后才跳转的页面链接——这点经常被忽略，导致反复重试 source。
