大家好,我是三十。今天想分享一个在团队里实际用到的工具------patch-package
。它很好地解决了一个我们可能都遇到过的问题:如何临时修复一个第三方 npm 包中的 bug。
事情起因是团队里一个项目在构建时突然报错,排查后发现问题出在一个间接依赖的包上。这个包有个小bug,但在我们的使用场景下会被触发。
开发环境下对 node-modules
中的源码进行调试修改后发现是可以修复的,所以决定将这一修改作为一个临时解决方案。
但大家都知道,这个目录下的改动既不能保存,也无法和团队共享。今天你改好了,明天同事拉代码或服务器部署时又会失败。
调研后决定先通过 patch-package 临时解决。
patch-package 的工作原理
在对 node_modules
中的源码进行修改后,运行 patch-package
命令,它会把你对 node_modules
的修改记录下来,生成一个补丁文件 .patch
文件,保存在项目根目录下的 patches
文件夹中。
这样我们只需要每次 install
之后再去执行这些补丁文件就可以了。
而为了项目中所有人都可以共享这些补丁,所以需要将补丁文件和项目本身一起提交到 git 仓库中。这样,一个本地临时的修改,就变成了一个可共享、可重复的解决方案。
最佳实践
对 node_modules 中的源码巴拉巴拉一顿操作后把 bug 修复了。
1. 安装 patch-package postinstall-postinstall
为什么要使用 postinstall-postinstall
,直接配置 postinstall
脚本不可以吗?后面 注意事项 中有解释。
csharp
yarn add patch-package postinstall-postinstall
2. 配置 package.json
在 package.json
文件中,添加一个 postinstall
脚本来确保在安装依赖后应用补丁:
json
"scripts": {
"postinstall": "patch-package"
}
3. 创建补丁
go
npx patch-package some-package # some-package 是 npm 包名
执行命令后会在项目根目录下创建一个 patches
文件夹,并在其中生成一个名为 xxxxx.patch
的补丁文件。
4. 提交补丁文件到代码仓库
sql
git add patches/xxxxx.patch
git commit -m "修改三方库中的 bug"
git push origin main
5. 安装依赖并应用补丁
当执行了 install 命令后,postinstall
脚本会自动运行,patch-package
会自动检测 patches
文件夹中的补丁,并将其应用到对应的依赖上。
注意事项
为什么使用 postinstall-postinstall
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
之后都能被执行。
总结
通过 patch-package
可以把临时解决方案变得规范起来,避免团队协作和部署时的坑。同时在使用时建议在项目文档或 README 中简单记录一下对哪个包打了补丁、原因是什么,方便后续追踪。
如果你还没遇到过类似问题,可以先把它收进工具箱;如果已经遇到了,希望这个分享能帮到你。