前端救急实战：用 patch-package 解决 vue-pdf 电子签章不显示问题

摘要：本文以 vue-pdf 渲染电子签章失效的典型问题为例，结合社区真实案例，手把手教你使用 patch-package 修改第三方库源码并生成持久化补丁。无需等待官方更新，快速修复线上 Bug！

一、问题重现：vue-pdf 电子签章为何神秘消失？

场景描述 ：使用 vue-pdf@4.3.0 预览带数字签章的 PDF 时，签章区域显示为空白。
根本原因 ：vue-pdf 依赖的底层库 pdfjs-dist 会主动隐藏签章注释。关键代码如下（位于 node_modules/pdfjs-dist/es5/build/pdf.worker.js）：

javascript 复制代码

// 原始问题代码  
if (data.fieldType === 'Sig') {  
  data.fieldValue = null;  
  _this3.setFlags(_util.AnnotationFlag.HIDDEN); // 强制隐藏签章  
}

此问题在官方仓库积压已久，短期无法修复。

二、patch-package 登场：5 分钟生成持久化补丁

▍ 核心原理

记录差异 ：将 node_modules 中的修改生成标准 Git Diff 补丁文件（.patch）
自动同步 ：通过 npm postinstall 钩子，在每次 npm install 后自动应用补丁

▍ 优势 vs 传统方案

方案	维护成本	团队协作	升级影响
整体 Copy 源码	高（需手动更新）	不可复用	完全脱离官方更新
Webpack Alias	中（配置复杂）	需统一配置	易冲突
patch-package	低（自动打补丁）	提交补丁文件	版本升级需重生成

三、实战修复：4 步解决签章不显示

步骤 1：安装工具链

bash 复制代码

npm install patch-package --save-dev  # 核心工具  
npm install postinstall-postinstall --save-dev  # 确保 yarn 兼容性

步骤 2：修改 node_modules 源码

打开文件：node_modules/pdfjs-dist/es5/build/pdf.worker.js
定位关键代码 （约 3.5 万行附近，搜索 fieldType === 'Sig'）
注释隐藏逻辑：

javascript 复制代码

if (data.fieldType === 'Sig') {  
  data.fieldValue = null;  
  // _this3.setFlags(_util.AnnotationFlag.HIDDEN); // ✅ 注释此行！  
}

步骤 3：生成补丁文件

bash 复制代码

npx patch-package pdfjs-dist  # 针对 pdfjs-dist 生成补丁

执行后生成：/patches/pdfjs-dist+4.8.69.patch（版本号以实际为准）

步骤 4：配置自动补丁

在 package.json 中添加 postinstall 脚本：

json 复制代码

{  
  "scripts": {  
    "postinstall": "patch-package"  // 安装依赖后自动打补丁  
  }  
}

✅ 验证补丁生效

bash 复制代码

rm -rf node_modules  # 删除旧依赖  
npm install         # 重装依赖

重新运行项目，签章应正常显示！

四、关键注意事项

版本锁定：
- 补丁绑定特定版本（如 pdfjs-dist@4.8.69）
- 升级依赖需重新生成补丁
json 复制代码
```
// 推荐锁定版本（package.json）  
"pdfjs-dist": "4.8.69"  
```
团队协作：
- 将 /patches 目录提交到 Git 仓库，队友拉取代码后执行 npm install 自动生效
长期维护建议：
- 在补丁文件头部添加注释说明问题原因：
  diff 复制代码
```
+ // Fix: Uncomment hidden signature logic  
+ // Ref: https://github.com/mozilla/pdf.js/issues/4242  
```
- 持续关注官方 Issue，推动合并修复

五、更多应用场景

除解决 vue-pdf 签章问题外，patch-package 还可用于：

修复样式问题 ：修改 antd 组件默认尺寸错乱
行为定制 ：调整 element-ui 表单验证触发逻辑
紧急绕过限制：解除某库的 License 校验逻辑

开发伦理：此方案仅推荐用于临时救急。长期项目仍应通过 Fork 维护或推动上游修复。

扩展阅读：

官方问题深度分析：《vue-pdf 签章渲染原理与源码破解》
patch-package 高级用法：为多个依赖生成联合补丁

行动号召 ：你在使用第三方库时遇到过哪些"致命 Bug"？评论区分享你的补丁实战经验，点赞最高送 Chrome 调试插件全家桶！

保持技术敏锐：点击关注，每周解锁前端黑科技！下期预告：《Babel 插件魔改：给 console.log 加上自动埋点》