如何在执行Composer命令时强制覆盖本地修改的 vendor 代码

Composer 开发中，你大概率遇到过这种场景：某个第三方包在 vendor/ 里被你一时手痒改了几行代码，结果再跑 composer install 或 composer update 时，它直接罢工，抛出一句 Changed files detected...。默认情况下，Composer 会校验包文件的哈希值，一旦发现跟你本地 vendor/ 里的内容对不上，它就拒绝继续执行。

这个机制的本意是防止你丢失手动改动的代码——出发点是好的。但问题在于，很多时候你根本不是想保留那些改动，恰恰相反，你就是想用上游的代码把本地这些乱七八糟的修改覆盖掉。这时候最干脆的做法是什么？直接告诉 Composer：别看那些东西了，按锁文件重装。

Composer install/update 时跳过 vendor 文件校验直接覆盖

关键就在于 --force 参数。在 Composer 2.2 及以上版本中，跑下面两条命令就能搞定：

composer install --force

composer update --force

注意，--force 在 2.2 之前还没正式支持。如果你还在用 1.x，那就只能走笨办法：删掉 vendor/ 目录再用 composer install 重装，期间配合 --no-scripts --no-plugins 避坑。这是权宜之计，不值得长期依赖。

为什么 git stash 在这里不灵？

不少人在 vendor/ 里试过 git stash，结果发现完全没效果。原因很简单：Composer 根本不靠 Git 状态来判定文件是否被改过，它对比的是文件实际内容生成的哈希值，跟 composer.lock 里记录的 dist source 或 commit hash 做校验。你 stash 了，文件内容变了，校验就失败。

• vendor/ 里的包来源不一定是 Git 克隆，很多是 zip 直接解压的。
• 就算是 Git 下载的，Composer 也不读 git status，它只读文件内容。
• 所以，别在 git stash 上浪费时间了，直接上 --force 才是正解。

composer update --force 的副作用要心里有数

--force 不光是跳过改动检测，它还会强制把所有包重新下载一遍，哪怕是 composer.lock 根本没变——相当于自带了一个隐式的 --no-cache。这意味着几下几点：

• 网络条件不好时，会很慢。国内没配镜像源的话，等起来能让你怀疑人生。
• 如果 composer.lock 里引用了私有包，且认证凭证已经过期，--force 可能会触发 401 授权错误。
• 它不会跳过脚本，post-install-cmd 等依然会执行——这一点跟 --no-scripts 是两回事。

如果你只是想覆盖改动，却不想把所有包都重下一遍，那可以更“精准”地操作：直接删掉出问题的那个包的目录，再跑一次 composer install。比如：

rm -rf vendor/monolog/monolog && composer install

长期来看，更可持续的解法是什么？

说到底，频繁手动修改 vendor/ 里的代码，本身就是一个开发流程上的坑。硬覆盖只是救火的手段，而不是常规的流程。真正可持续的做法是：

• 用 composer patch 来管理补丁（比如 cweagans/composer-patches 这个插件），把改动沉淀为补丁文件，而不是直接改源码。
• 调试阶段优先用 Xdebug 断点或简单的 dump() 打日志，而不是去改 vendor 里的代码。
• 如果确实需要改底层逻辑，最好的方式是 fork 对应包，提交 PR，然后用 "package-name": "dev-main as 1.2.3" 的方式引入你自己的分支。

每次敲 --force 的时候，都不妨问自己一句：这个地方，是不是该换个更可持续的解决方式了？