当前位置：首页 > news >正文

【实录】使用 patch-package 修复第三方 npm 包中的 Bug

news 2025/10/11 6:07:36

大家好，我是三十。今天想分享一个在团队里实际用到的工具——patch-package。它很好地解决了一个我们可能都遇到过的问题：如何临时修复一个第三方 npm 包中的 bug。

事情起因是团队里一个项目在构建时突然报错，排查后发现问题出在一个间接依赖的包上。这个包有个小bug，但在我们的使用场景下会被触发。

开发环境下对 node-modules 中的源码进行调试修改后发现是可以修复的，所以决定将这一修改作为一个临时解决方案。

但大家都知道，这个目录下的改动既不能保存，也无法和团队共享。今天你改好了，明天同事拉代码或服务器部署时又会失败。

调研后决定先通过 patch-package 临时解决。

在对 node_modules 中的源码进行修改后，运行 patch-package 命令，它会把你对 node_modules 的修改记录下来，生成一个补丁文件 .patch 文件，保存在项目根目录下的 patches 文件夹中。

这样我们只需要每次 install 之后再去执行这些补丁文件就可以了。

而为了项目中所有人都可以共享这些补丁，所以需要将补丁文件和项目本身一起提交到 git 仓库中。这样，一个本地临时的修改，就变成了一个可共享、可重复的解决方案。

对 node_modules 中的源码巴拉巴拉一顿操作后把 bug 修复了。

为什么要使用 postinstall-postinstall，直接配置 postinstall 脚本不可以吗？后面 注意事项 中有解释。

yarn add patch-package postinstall-postinstall

在 package.json 文件中，添加一个 postinstall 脚本来确保在安装依赖后应用补丁：

"scripts": {"postinstall": "patch-package"
}

npx patch-package some-package # some-package 是 npm 包名

执行命令后会在项目根目录下创建一个 patches 文件夹，并在其中生成一个名为 xxxxx.patch 的补丁文件。

git add patches/xxxxx.patch
git commit -m "修改三方库中的 bug"
git push origin main

当执行了 install 命令后，postinstall 脚本会自动运行，patch-package 会自动检测 patches 文件夹中的补丁，并将其应用到对应的依赖上。

Yarn 和 npm 对 postinstall 脚本的触发行为有差异：

npm: 在运行 npm install 后，它会自动运行 postinstall 脚本。
yarn: 在 v1 版本的默认情况下，postinstall 脚本只会在你 直接安装 某个包（例如 yarn add package-x）之后运行，但在后续 单纯运行 yarn 或 yarn install 来安装所有依赖时，它不会自动运行。

这就导致一个问题：如果你只按照常规配置 "postinstall": "patch-package"，那么当你的同事克隆项目后运行 yarn install，补丁可能根本不会被应用！

而 postinstall-postinstall 这个包，则可以确保 postinstall 脚本在 每一次 yarn install 之后都能被执行。