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

大家好,我是三十。今天想分享一个在团队里实际用到的工具------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 脚本不可以吗?后面 注意事项 中有解释。

复制代码
yarn add patch-package postinstall-postinstall

2. 配置 package.json

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

复制代码
"scripts": {
  "postinstall": "patch-package"
}

3. 创建补丁

复制代码
npx patch-package some-package # some-package 是 npm 包名

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

4. 提交补丁文件到代码仓库

复制代码
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 中简单记录一下对哪个包打了补丁、原因是什么,方便后续追踪。

如果你还没遇到过类似问题,可以先把它收进工具箱;如果已经遇到了,希望这个分享能帮到你。

相关推荐
Mh3 小时前
我是如何设计品牌站组件库的?
前端·css·设计模式
程序员大阳4 小时前
副队长Vue3教程(2)--Vite 搭建 Vue 项目,认识目录结构
前端·javascript·vue.js·vite·创建项目·目录结构·项目结构
濮水大叔4 小时前
Cabloy/Zova 与 Next.js 的 SSR 水合差异
前端·typescript·next.js
SoaringHeart5 小时前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
Flynt6 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
北城笑笑6 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星7 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson7 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
其实防守也摸鱼8 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊8 小时前
CNC计算机数控加工模拟器
前端