pnpm patch 补丁指南

pnpm patch 补丁指南

什么是 pnpm patch？

pnpm patch 允许你在不 fork 仓库的情况下，直接修改 node_modules 中第三方包的代码，并将修改以补丁文件的形式保存在项目中。

每次 pnpm install 时会自动应用补丁，适用于本地开发和 CI/CD 部署（如 Vercel）。

使用场景

• 第三方包有 bug，但作者还没修复
• 需要移除不需要的功能（如本项目移除 markitdown-ts 的 PDF 解析）
• 临时修复兼容性问题

操作步骤

1. 启动补丁编辑

pnpm patch <package-name>@<version>

示例：

pnpm patch markitdown-ts@0.0.10

执行后会输出一个临时编辑目录路径：

Patch: You can now edit the package at:
  /your-project/node_modules/.pnpm_patches/markitdown-ts@0.0.10

2. 编辑代码

进入该目录，修改你需要改的文件。例如：

• 删除不需要的 import
• 移除不需要的类或函数
• 修改 package.json 中的依赖

3. 提交补丁

pnpm patch-commit '/your-project/node_modules/.pnpm_patches/markitdown-ts@0.0.10'

这会在项目根目录生成 patches/markitdown-ts@0.0.10.patch 文件。

4. 配置 package.json

在 package.json 中添加补丁配置：

{
  "pnpm": {
    "patchedDependencies": {
      "markitdown-ts@0.0.10": "patches/markitdown-ts@0.0.10.patch"
    }
  }
}

5. 验证

pnpm install

安装完成后检查 node_modules 中的包是否已应用补丁。

提交到 Git

确保以下文件提交到仓库：

patches/markitdown-ts@0.0.10.patch   # 补丁文件
package.json                          # 含 pnpm.patchedDependencies 配置

部署平台（如 Vercel）执行 pnpm install 时会自动应用补丁。

实际案例：移除 markitdown-ts 的 PDF 功能

本项目中 markitdown-ts 依赖了 pdf-parse → pdfjs-dist，而 pdfjs-dist 需要浏览器 API（DOMMatrix），在 Serverless 环境中不可用。

补丁修改了 3 个文件：

文件	修改内容
dist/index.mjs	移除 import { PDFParse } 和 PdfConverter 类
dist/index.cjs	移除 require('pdf-parse') 和 PdfConverter 类
package.json	移除 pdf-parse 依赖

常用命令

命令	说明
pnpm patch <pkg>@<ver>	启动补丁编辑
pnpm patch-commit <path>	提交补丁
pnpm install	安装依赖并自动应用补丁