pnpm patch 是 pnpm 包管理器自带的一条命令,用来给第三方依赖打补丁。装好的包在 node_modules 里直接改,下次安装就会被覆盖;这条命令先把包解压到 node_modules/.pnpm_patches/<pkg> 这样的目录,你在里面随意改,改完再跑 pnpm patch-commit 生成补丁文件,并写进顶层清单的 patchedDependencies 字段,之后每次安装都会自动应用。
用法是 pnpm patch <pkg name>@<version>,前提是先跑过 pnpm install,没有 lockfile 会直接报 ERR_PNPM_PATCH_NO_LOCKFILE。同一个包装了多个版本时,它会先问你要补哪个版本,再问是否应用到所有版本;选全部版本的话,patchedDependencies 的键就不带版本号。
主要功能
除了默认目录,可以用 --edit-dir(-d)指定解压位置;目录已存在且非空会报错,不加这个选项而默认目录非空同样会失败。--ignore-existing 则在打补丁时忽略已有的补丁文件。
patchedDependencies 支持按精确版本、版本范围或只写包名来匹配,优先级从高到低是精确版本、版本范围、仅包名。文档提醒不要写重叠的版本范围,需要单独处理某个子区间时,把它从大范围里显式排除。allowUnusedPatches 默认为 false,设成 true 后,补丁没被用上也不会让安装失败;但补丁应用失败仍然会让安装失败,同一组里多个补丁会全部尝试,错误最后一起报。
适合谁
适合用 pnpm 管理项目、又碰上依赖包有 bug 或需要小改的 Node.js 开发者。官方明确说,要改一个包的依赖关系不要用 pnpm patch 去动它的 package.json,应该用 overrides 或 package hook。
费用与限制
命令本身随 pnpm 免费提供,页面是英文文档。它只解决改代码的问题,不解决依赖解析;补丁文件要跟着仓库一起提交,否则别人装不上。
