--prefer-dist是“有dist包则用，无则自动回退source”的策略，非强制加速开关；生效需包提供dist URL，CI/Docker等无Git环境才真正必要。
--prefer-dist 不是加速开关，而是“有压缩包就用，没有就退回去”的策略声明；它在 CI、Docker 或无 Git 环境里才真正必要，本地开发通常不需要显式加。
怎么确认 --prefer-dist 实际生效了
别只看命令里有没有 --prefer-dist，得看行为：
- 加
-v运行composer install -v，输出中出现Downloading https://...（URL 含tarball、zipball或archive）且无Cloning或git clone字样，才算真走 dist - 检查
vendor/some/package目录：没有.git文件夹，基本可断定是 dist 模式 - 运行
composer show vendor/package -s，若dist字段非空（含url和sha256），说明该包支持 dist 安装
为什么加了 --prefer-dist 还在 git clone
常见原因不是参数没写对，而是 dist 包不可用或被覆盖：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 包本身没发布 tag（比如只推了
dev-main），Packagist 就不会生成 dist URL，Composer 自动 fallback 到 source -
composer.json里写了"preferred-install": {"*": "source"}，它会覆盖命令行参数 - 环境变量
COMPOSER_PREFER_SOURCE=1已设置，优先级高于命令行 - 私有仓库（如 GitLab）未开启
archive功能，或未配置dist字段，Composer 找不到压缩包地址
CI 构建卡在 Cloning into 'vendor/xxx' 怎么办
这几乎一定是误用了 source 模式，而非网络或权限问题：
- 先 grep 项目中的
composer.json和 CI 脚本，搜prefer-source、"preferred-install"、COMPOSER_PREFER_SOURCE - Docker 镜像（如
php:alpine）默认不带git，装 git 是临时补救，不如直接切回--prefer-dist - 若必须用 source（例如调试私有包），确保构建机已配好 SSH key 或 GitHub token，并允许访问
git@github.com或对应端口 - dist 模式走 HTTPS 下载，只要能通 Packagist 或 GitHub Releases 即可，不依赖 git 命令或 SSH
composer.json 里怎么安全配 preferred-install
全局设 "*": "source" 是高危操作，尤其团队协作时：
- 推荐按前缀控制：
"myorg/*": "source"（自家包可调试） +"*": "dist"（第三方一律压缩包） -
"*": "dist"必须放在最后，否则会覆盖所有前面的规则 - 匹配是「包名前缀」，不是 glob：
"monolog"不匹配monolog/monolog，得写成"monolog/"或"monolog/*" - 本地开发用
"*": "source"会导致每个vendor目录多出几十 MB 的.git，git status变慢，composer update更耗时
最常被忽略的一点：--prefer-dist 生效的前提是包本身提供了 dist URL；它不造包，只选包。如果你维护的是私有包，记得在 composer.json 里配好 dist 字段，或启用 Git 仓库的 archive 功能，否则无论怎么加参数都只能 fallback。
