Composer的--prefer-dist和--prefer-source区别

CI中composer install卡在Cloning是因误用--prefer-source且构建机缺Git或SSH配置；应改用--prefer-dist并禁用dev依赖与autoloader扫描。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

为什么CI里composer install卡在Cloning into 'vendor/xxx'？

这个问题，在持续集成（CI）环境里太常见了。十有八九，是脚本里误用了--prefer-source参数，而构建服务器上要么没装Git，要么SSH密钥配置不全。要知道，CI环境出于安全和效率考虑，通常会禁用Git协议、屏蔽GitHub等域名，或者干脆不配置部署密钥。这时候如果还坚持用--prefer-source去克隆源码，结果不是直接报错，就是无限等待，卡得你怀疑人生。

正确的做法其实很明确：要么在命令里显式加上--prefer-dist，要么去检查一下composer.json，确保全局配置里没有设置"preferred-install": "source"。在CI脚本里，通常建议这样写，一步到位：

composer install --no-dev --prefer-dist --optimize-autoloader

这个组合拳效果显著：跳过Git克隆、忽略开发依赖、还优化了自动加载器扫描，可以说是为CI环境量身定做的“三重提速”方案。

本地调试时git checkout进不去vendor目录？

这又是另一个极端了。很多开发者习惯在本地用git checkout去切换vendor里某个包的版本，结果发现命令无效。原因很简单：默认情况下，Composer使用--prefer-dist，下载的是打包好的ZIP文件，解压后的vendor目录里根本没有.git文件夹。你试试ls -A vendor/monolog/monolog | grep git，返回肯定是空的——它压根就不是一个Git仓库，你怎么能对它执行Git操作呢？

如果确实需要在vendor目录里进行git checkout dev-main或者git diff这类操作，那就必须用--prefer-source方式安装这个特定的包：

• 安装时指定：composer require monolog/monolog --prefer-source
• 或者只更新某一个：composer update monolog/monolog --prefer-source

安装完成后，可以进到vendor/monolog/monolog目录，执行一下git log -n 3来确认已经有了完整的提交历史。

这里有个重要的提醒：如果你在本地vendor里修改了代码并提交了，下次执行composer update时，默认行为是不会保留这些本地commit的。所以，记得先把修改推送到你自己的代码分支上。

preferred-install配置写错导致全项目变慢？

配置文件的顺序，有时候就是性能的杀手。一个常见的“翻车”配置是这样的：

"config": {
  "preferred-install": {
    "*": "dist",
    "myorg/*": "source"
  }
}

看起来是想让所有包默认用dist，但自己组织的包用source。可惜，通配符*的匹配优先级（或者说，Composer的解析顺序）让后面的myorg/*规则永远不生效——因为*已经匹配了所有包。正确的顺序应该是“精确优先”，把具体的规则放在前面：

"config": {
  "preferred-install": {
    "myorg/*": "source",
    "*": "dist"
  }
}

另外，匹配模式也有讲究。"monolog"这种写法是无效的，因为它缺少了/。正确的写法应该是"monolog/*"，这样才能命中像monolog/monolog、monolog/php-handler这样的所有相关包。

用--prefer-source就能拿到最新代码？

这是一个普遍的误解。需要明确的是，--prefer-source只是改变了安装方式（从下载ZIP包变为克隆Git仓库），但它克隆的代码版本，依然严格受composer.lock文件控制。

具体来说，Composer会去克隆composer.lock里锁定的那个具体的commit hash，而不是远程仓库main分支的最新提交。比如lock文件里记录着"reference": "a1b2c3d"，那么--prefer-source就只会检出这个“a1b2c3d”提交，哪怕上游仓库的main分支已经又推进了20个新提交。

真想获取某个包的最新代码，有两种方法：要么进入对应的vendor子目录手动执行git pull；要么就使用composer update --prefer-source来更新这个包，这会触发Composer重新解析依赖并生成新的lock文件。

说到底，一个包能否被更新到“最新”版本，根本取决于包作者是否发布了新的tag，或者更新了composer.json里的version字段。这与安装时用dist还是source方式，没有直接关系。