Hexo 使用 patch‑package 保存 node_modules 修改

适用场景：你手动修改了 node_modules 内部第三方包源码，重装依赖、换电脑迁移会丢失改动。

什么是 patch‑package

直接修改 node_modules 只是临时效果，执行 npm install 就会被官方原版覆盖。 patch‑package 对比你修改前后代码，生成 patches/*.patch 补丁文件，提交进仓库；执行 npm install 自动把你的修改打回去，实现换电脑、重装依赖改动不丢失。

Hexo 博客迁移电脑不再复制庞大、容易出错的 node_modules。

一、旧电脑生成补丁步骤

1、安装 patch‑package

进入你的 Hexo 项目根目录（package.json所在文件夹）执行：

npm install patch-package --save-dev

2、修改 package.json scripts，增加 postinstall

{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo clean && hexo generate && hexo deploy && python push_baidu.py && hexo clean",
    "server": "hexo server",
    "postinstall": "patch-package"  //这里添加
  },
  "hexo": {
    "version": "8.1.1"
  },
  "dependencies": {
    // 你的原有依赖不动
  },
  "devDependencies": {
    "patch-package": "^8.0.1"
  }
}

"postinstall": "patch-package"：每次npm install结束自动执行补丁应用，不要手动运行这条命令，npm 会自动调用。

3、确认你的修改还在

关键前提，千万不要执行 npm install！ 打开你改动过的 node_modules/包名/xxx.js，确认你的手动修改已经保存。

一旦运行npm install，node_modules 恢复原版，改动直接消失，无法生成补丁。

4、生成补丁文件

项目根目录执行，把包名替换成你修改的包文件夹名字（node_modules/后面的文件夹名）。

npx patch-package 包名

示例：修改了 node_modules/hexo-renderer-kramed

npx patch-package hexo-renderer-kramed

成功输出

created patch file patches/hexo-renderer-kramed+0.1.4.patch

项目根目录出现全新 patches 文件夹，补丁文件就在这里。

报错：There don't appear to be any changes

含义：没有检测到任何改动。 原因：

  1. 你的修改已经丢失（执行过 npm install），需要重新手动改 node_modules 里面文件，保存，立刻执行上面命令；
  2. 包名字写错；
  3. 不在项目根目录执行命令。

5、git 提交文件清单

提交到 git

  • patches/整个文件夹
  • package.json
  • package‑lock.json
  • source/、themes/、_config.yml等博客源码配置

绝对不要提交

  • node_modules/

.gitignore确保有这几行

node_modules/
public/
.deploy_git/
db.json

提交示例：

git add patches package.json package-lock.json
git commit -m "patch:保存第三方依赖自定义修改"

二、新电脑迁移完整步骤

  1. 新电脑安装 和旧电脑一致大版本 Node.js，安装 Git。
# 旧电脑查看版本
node -v
  1. 获取博客源码 两种方式任选其一
  • git clone 你的仓库；
  • 拷贝本地项目文件夹（不要拷贝 node_modules）。
  1. Hexo 全局命令（如需要）
npm install -g hexo-cli
  1. 安装项目依赖（核心）
npm install

npm install 完成之后自动触发postinstall，控制台会打印Applying patches...，自动应用你写的修改，无需手动操作GitHub。

  1. 测试运行博客
npm run server

访问 http://localhost:4000，验证你对依赖的自定义修改已经生效。

三、本地测试补丁是否有效

生成补丁完成后，本地模拟迁移环境：

# 删除本地node_modules
rm -rf node_modules
# 重新安装依赖，看补丁自动打上
npm install
npm run server

如果功能正常，代表补丁完全没问题，可以放心迁移电脑。

四、应急临时迁移方案

仅用于临时搬家，不要提交 node_modules 到 git 仓库

  1. 旧电脑复制整个项目文件夹，包含已经修改好的 node_modules；
  2. 拷贝到新电脑，直接运行npm run server；
  3. 新电脑跑通之后，立刻按照教程生成patches补丁，后续不再依赖拷贝 node_modules。

五、常见踩坑

  1. 升级被打补丁的 npm 包

补丁文件记录的是特定版本差异，一旦升级该依赖包，补丁大概率失效。 需要：重新修改新版本node_modules源码 → 再次执行npx patch-package 包名重新生成补丁。

  1. 部署 CI/GitHub Actions

只需要正常执行npm install，postinstall 钩子会自动打补丁，不需要额外脚本。

  1. 区分主题修改和依赖修改
  • 修改themes/xxx：你的博客源码，直接 git 提交，不需要 patch‑package；
  • 修改node_modules/xxx第三方库源码：必须使用 patch‑package。
  1. 查看补丁是否执行成功 运行npm install，看控制台输出是否打印 Applying patches... xxx ✔，代表补丁成功应用。

六、命令速查表

# 安装工具
npm install patch-package --save-dev

# 生成补丁
npx patch-package 包名

# 测试补丁（模拟新电脑环境）
rm -rf node_modules
npm install
npm run server