composer中如何通过–prefer-dist加速大型包的下载_composer下载模式选择【详解】

–prefer-dist 优先下载压缩包，速度快、开销小；–prefer-source 强制克隆完整仓库，适合调试。composer 默认自动选择，但受包配置、lock 文件、环境变量等影响，需显式指定或配置 preferred-install 确保生效。

什么是 –prefer-dist 和 –prefer-source

--prefer-dist 告诉 Composer 优先从包的 发布版本（dist） 下载，通常是压缩包（如 .tar.gz 或 .zip），由 Packagist 缓存并分发；--prefer-source 则强制克隆源码仓库（如 git），适合需要修改包代码或调试时使用。

大型包（比如 laravel/framework、symfony/symfony）含大量历史提交和开发分支，--prefer-source 会完整 clone 整个仓库，耗时长、占磁盘多；而 --prefer-dist 只下载当前版本的精简归档，解压快、网络开销小、IO 压力低。

为什么默认不总是用 –prefer-dist

Composer 默认行为是「自动选择」：多数情况下选 dist，但某些条件会回退到 source，例如：

• 包未配置 dist 信息（如私有仓库未打 tag 或未配置 archive）
• 本地 composer.json 中该包被设为 "dev-master" 或其他开发版约束，且未提供 dist URL
• 启用了 COMPOSER_PREFER_SOURCE=1 环境变量
• 运行了 composer install 但 composer.lock 记录的是 source 安装方式（可能源于之前手动加了 --prefer-source）

所以不能只靠“默认”，得显式控制。

如何确保大型包走 –prefer-dist

最直接有效的方式是在安装/更新命令中加参数：

composer install --prefer-dist composer update --prefer-dist composer require monolog/monolog --prefer-dist

若想全局生效（推荐 CI/CD 或团队统一环境）：

• 在项目根目录写 composer.json，添加：

  "config": {   "preferred-install": "dist" }

• 或全局设置（影响所有项目）：

  composer config -g preferred-install dist

注意："preferred-install" 支持通配符，比如 "*": "dist"、"vendor/*": "dist"，但对大型包，直接设 "*": "dist" 最稳妥。

常见失效场景与排查方法

即使写了 --prefer-dist，仍可能走 source，典型原因：

• 包本身没提供 dist —— 查看 composer show vendor/package 输出，若 dist 字段为空或显示 type: git，说明没 dist 发布
• composer.lock 已锁定为 source 方式 —— 删除 composer.lock 和 vendor/ 后重试
• 用了 repositories 自定义源，但未正确配置 dist URL 或 archive 模板
• 运行 composer update vendor/package 时，该包在 composer.lock 中记录为 source，且未加 --prefer-dist，Composer 会复用旧方式

验证是否成功：安装后进 vendor/vendor-name/package/，执行 ls -la。如果看到 .git 目录，说明走了 source；没看到且有 composer.json + 正常代码文件，基本就是 dist。

真正影响速度的不是参数名本身，而是 dist 包是否真实存在、能否被命中。很多团队卡在“以为加了就生效”，其实漏查了 lock 文件或私有源配置 —— 这点比记住命令更重要。