Composer怎么指定安装优先dist还是source_Composer prefer参数区别【核心】

在日常开发中，经常有人问：Composer 安装依赖时，到底该用 `--prefer-dist` 还是 `--prefer-source`？这俩参数虽然只差一个词，但背后的行为差异，直接影响构建效率、调试体验，甚至在 CI 环境里导致诡异的卡死。 **绝大多数时候该用 `--prefer-dist`，它快、轻、稳；只有真要改 `vendor` 里的代码时，才必须上 `--prefer-source`。** 下面就从几个高频场景，拆解一下这两个参数的正确用法，以及背后那些容易踩的坑。 ### CI 构建卡在 `Cloning into 'vendor/some/package'` 怎么办 这基本是误用了 `--prefer-source`，而构建机没装 Git、没配 SSH key，或网络屏蔽了 GitHub 的 git 端口（9418）。dist 包走 HTTPS 下载，只要能访问 Packagist 或 GitHub Releases 就行；source 模式强依赖 `git` 命令可用、远程仓库可连、SSH/HTTPS 认证通过。 - CI 镜像（如 `php:alpine`）默认不带 Git，`apt-get install git` 是临时补救，但不如直接切回 `--prefer-dist` - 检查 CI 日志里是否出现 `git clone` 或 `Cloning into` —— 有就是被 `--prefer-source` 或 `"preferred-install": "source"` 触发了 - 本地 `composer install` 正常，CI 却卡住？优先 grep 项目中的 `composer.json` 和 CI 脚本，确认有没有全局或命令行传入 `--prefer-source` ### `composer.json` 里怎么安全配置 `preferred-install` 别全局设 `"preferred-install": "source"`，尤其团队协作时：所有人本地 `vendor` 都多出几十 MB `.git` 目录，CI 构建也变慢，还可能因 Git 配置不一致报错。 - 推荐按包控制：`"myorg/*": "source"`（自家私有包可调试） + `"*": "dist"`（第三方一律压缩包） - 通配符 `*` 必须放最后，否则 `"*": "dist"` 写在前面会覆盖掉所有自定义规则 - 匹配是「包名前缀」，不是 glob：`"monolog"` 不匹配 `monolog/monolog`，必须写成 `"monolog/"` 或 `"monolog/*"` - 配置生效需重跑 `composer install` 或 `composer update`，已有 `vendor` 不会自动重装 ### `composer show vendor/package` 看不出支持哪种安装方式？ 执行后看输出里的 `source` 和 `dist` 字段是否都有 URL。没有 `source` 地址的包，加 `--prefer-source` 也没用，必然 fallback 到 dist。 - 常见情况：小众包或私有包只提供 dist，因为作者没在 `composer.json` 里配 `source` URL - GitHub 仓库若未打 tag，Packagist 可能只索引到 dist（Release ZIP），而 `source` 信息为空 - `dist` 对应的是某个稳定 tag（如 `v3.5.0`），`source` 克隆的是默认分支（如 `main`），两者语义不同，不是“新旧”关系 - 即使加了 `--prefer-source`，若某包没配 `source` URL，Composer 也会自动降级为 dist —— 所以卡住 ≠ 一定成功回退 ### `--prefer-source` 安装后改了代码，下次 `update` 会丢吗 会丢。除非你手动 `git commit` 并确保没被 `composer update` 的 checkout 覆盖。真正容易被忽略的点是：`source` 安装后，你进 `vendor/some/package` 能 `git checkout`，但下次 `composer update` 默认不会保留你的修改 —— 因为它拉的是 `composer.lock` 里锁定的 commit hash，不是你当前分支头。 - 想保留 patch，得先 `git add && git commit -m "temp fix"`，再确保 `composer update` 不触发强制 reset - 配合 `"repositories": [{"type": "path", "url": "../my-local-package"}]` 时，`--prefer-source` 是刚需，否则报错：`Package is not installed as source` - `--prefer-source` 下，`composer update` 会执行 `git fetch + git checkout`，可能因分支重写失败；`--prefer-dist` 则只校验 SHA256，更稳定