patch-package 参考手册

给 node_modules 中的包打补丁，持久化本地修改，让 npm install 后补丁自动应用。 官方仓库：dsernst/patch-package (opens new window)

解决什么问题

当你需要修改 node_modules 里某个包的源码（比如改 bug、加功能、调样式），但又不想 fork 整个仓库时，patch-package 可以：

1. 把你对 node_modules 的修改生成一个 .patch 文件
2. 提交到 git 仓库
3. 执行 npm install 后，自动把补丁重新应用回去

安装

npm install patch-package --save-dev

然后在 package.json 的 scripts 中添加 postinstall 钩子，让每次 npm install 后自动应用补丁：

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

基本使用流程

1. 修改 node_modules 中的代码

直接编辑 node_modules/<包名>/ 下的源码，做你需要的修改。

2. 生成补丁文件

npx patch-package <包名>

例如：

npx patch-package vuepress-theme-vdoing

执行后会在项目根目录的 patches/ 下生成补丁文件，命名格式：

patches/<包名>+<版本号>.patch

例如：patches/vuepress-theme-vdoing+1.12.8.patch

3. 提交补丁文件到 git

把 patches/ 目录提交到版本控制，团队其他人 clone 后执行 npm install 就会自动应用补丁。

常用命令

命令	说明
npx patch-package <包名>	生成补丁（修改后执行）
npx patch-package	应用所有补丁（postinstall 自动调用）
npx patch-package --reverse <包名>	撤销某个包的补丁
npx patch-package --use-yarn	使用 yarn 而不是 npm
npx patch-package --create-issue	基于补丁在 GitHub 上提 issue

实际项目示例

本项目中为 vdoing 主题添加目录中文显示名称功能，修改了以下文件：

• node_modules/vuepress-theme-vdoing/node_utils/getSidebarData.js
• node_modules/vuepress-theme-vdoing/components/Catalogue.vue
• node_modules/vuepress-theme-vdoing/components/SidebarGroup.vue
• node_modules/vuepress-theme-vdoing/util/index.js

修改完成后执行：

npx patch-package vuepress-theme-vdoing

生成补丁文件 patches/vuepress-theme-vdoing+1.12.8.patch。

注意事项

1. 包版本必须匹配：补丁文件里记录了包版本，升级包版本后需要重新生成补丁
2. 修改后重新生成：每次修改 node_modules 后都要重新执行 npx patch-package <包名> 更新补丁文件
3. node_modules 被删除后：只要有 postinstall 钩子，重新 npm install 会自动应用补丁
4. 多包管理器：项目同时有 yarn.lock 和 package-lock.json 时，patch-package 默认用 npm，可用 --use-yarn 指定

工作原理

npm install → 安装所有依赖 → postinstall 钩子 → patch-package → 读取 patches/*.patch → 应用到 node_modules

补丁文件本质上是标准的 unified diff 格式，记录了你对原始包的每一处修改。