前端依赖库源码修改神器——patch-package 使用指南

前端依赖库源码修改神器——patch-package 使用指南

在现代前端项目中，我们通常通过 npm 或 cnpm 安装各种第三方依赖库。这些库通常已经打包好了，直接引用 node_modules 下的文件就能用。但是，有时候我们需要修改依赖库的源码——修复 bug、添加功能或者兼容特殊场景。

直接修改 node_modules 里的代码非常危险：下一次安装依赖时改动会被覆盖。这个时候，patch-package 就能派上用场。

---

什么是 patch-package？

patch-package 是一个开源工具，可以在 不 fork 依赖库 的情况下修改第三方库，并保证改动在每次依赖安装后自动生效。它的核心原理是：

1. 修改 node_modules 下的文件

2. 生成一个补丁文件（.patch）保存你的修改

3. 每次执行 npm install 或 yarn install 时自动应用补丁

安装 patch-package

# 使用 npm
npm install patch-package postinstall-postinstall --save-dev

# 使用 cnpm
cnpm install patch-package postinstall-postinstall --save-dev

配置 package.json

在 package.json 的 "scripts" 添加 postinstall：

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

这样每次执行 npm install、yarn install 或 cnpm install 时，补丁都会自动应用到依赖库里。

使用流程示例

假设我们想修改依赖库 jexcel：

1. 修改依赖库源码

找到 node_modules/jexcel/ 下你想修改的文件，直接修改。例如：

node_modules/jexcel/dist/jexcel.js

注意：如果依赖库是源码 + 构建产物结构（src + dist），建议修改 src 并重新构建，再生成补丁。

2. 生成补丁文件

npx patch-package jexcel

生成文件路径：

patches/jexcel+3.0.0.patch

这个 .patch 文件就是你对 jexcel 的改动记录。

3. 提交补丁文件

将 patches 文件夹提交到 git 仓库，这样团队其他人拉代码时，也能自动应用改动。

4. 检查补丁是否生效

• 删除 node_modules/jexcel 或重新安装依赖

• 执行 npm install

• 查看改动是否自动生效

小技巧和注意事项

1. 修改 dist 还是 src

   • 如果依赖库只有构建后的 dist，修改 dist 即可

   • 如果依赖库有源码（src），建议修改 src 并构建，再生成补丁，这样更可维护

2. 删除依赖库或改动

   • 删除补丁文件，删除依赖库，清理引用即可

   • 补丁依赖于 node_modules，没有对应依赖会报错