大家好,我是三十。今天想分享一个在团队里实际用到的工具------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-postinstall2. 配置 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 main5. 安装依赖并应用补丁
当执行了 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 中简单记录一下对哪个包打了补丁、原因是什么,方便后续追踪。
如果你还没遇到过类似问题,可以先把它收进工具箱;如果已经遇到了,希望这个分享能帮到你。