Composer 默认优先使用 --prefer-dist 模式，通过 config.preferred-install 配置 {"*": "dist"} 实现；适合生产部署与 CI 构建，速度快、体积小、不依赖 Git；--prefer-source 适用于调试、打补丁或开发分支切换，需克隆完整 Git 仓库。

composer install 和 update 默认用什么模式

Composer 默认优先使用 --prefer-dist，只要包在 dist（如 ZIP 归档）和 source（Git 仓库）两种方式都提供，它就会下载预打包的压缩包。这个行为由 config.preferred-install 控制，默认值是 {"*": "dist"}。

--prefer-dist 适合哪些场景

它从 Packagist 提供的 CDN 链接下载已构建好的 ZIP/TAR 包，速度快、不依赖 Git、不保留 .git 目录，适合生产环境部署和 CI 构建。

• 下载体积小（不含历史提交、测试文件、.git 目录）
• 安装快，尤其网络条件一般时明显优于 source
• 不会因本地 Git 配置（如 proxy、credential helper）失败而中断
• 生成的 vendor 目录更“干净”，无法执行 git pull 或 git log

如果你只是运行项目，不需要改依赖源码，--prefer-dist 是更稳妥的选择。

--prefer-source 什么时候必须用

它会克隆完整的 Git 仓库到 vendor/xxx/xxx，适用于需要调试、打补丁、或开发中频繁切换分支的场景。

• 能直接在 vendor 里改代码、提交、切分支（比如临时 patch 某个 bug）
• 某些包没发布 dist（例如私有仓库未配置 archive，或 packagist.org 上标记为 "archive": false）
• 你明确需要 .git 目录（例如某些工具依赖 git 插件读取版本信息）
• 本地 composer.json 中该包用了 "dev-master" 或 "dev-feature/xxx" 这类开发版约束时，Composer 通常自动 fallback 到 source

composer require monolog/monolog:dev-main --prefer-source

常见误操作与陷阱

很多人以为加了 --prefer-source 就能“永久保留 Git 状态”，但其实：

• composer update 仍可能把 source 切回 dist —— 取决于当前包的版本约束是否匹配 dist 发布的 tag
• 私有 GitLab/GitHub 仓库若未配置 dist URL（如缺少 archive 配置），即使加 --prefer-dist 也会退化为 source
• composer install --prefer-source 不会覆盖已存在的 dist 安装；得先删掉 vendor 或用 --force-reinstall
• 某些企业镜像（如腾讯云 TKE Composer 镜像）只缓存 dist，--prefer-source 会绕过镜像直连原始 Git 服务器，可能超时或被墙

真正要锁定 source 模式，得在 composer.json 里写死：

"config": {
  "preferred-install": {"my-private/package": "source"},
  "sort-packages": true
}

dist 和 source 的选择不是“哪个更好”，而是“哪个更符合当前动作的目的”。改依赖就 source，发版就 dist，混用容易导致 vendor 状态不可控。