MuPDF.js数据脱敏实战：如何永久擦除PDF中的敏感内容（Redaction）？

MuPDF.js数据脱敏实战：如何永久擦除PDF中的敏感内容（Redaction）？

【免费下载链接】mupdf.jsJavaScript bindings for MuPDF项目地址: https://gitcode.com/gh_mirrors/mu/mupdf.js

MuPDF.js 是 MuPDF 官方出品的 JavaScript / TypeScript 绑定库（npm 包名mupdf），基于 WebAssembly 运行，支持在 Node.js、浏览器、Bun、Deno 中完成 PDF 的渲染、编辑与数据脱敏。本文将带你用 Redaction（红action）功能，真正永久擦除PDF 中的敏感内容，而不是画一条"看起来像"的黑条。

为什么必须用 Redaction 做数据脱敏？

很多人以为"在敏感信息上盖个黑条"就算脱敏了。其实这只是视觉遮盖——原始文字仍然留在 PDF 文件流里，任何人用文本提取工具都能一键还原。真正合规的脱敏必须满足：

• 🧹物理删除：文字对象从 PDF 内容流中彻底移除
• 🖼️区域涂抹：被遮盖区域内的文字按"触碰到即删除"的规则清除
• 💾可持久化：保存后无法通过任何手段恢复原文

MuPDF.js 的Redact类型注释正好实现了这套标准流程，这也是 PDF 规范中 Redaction 的定义行为。

快速上手：3步完成一次 PDF 内容擦除

以docs/how-to-guide/annotations/redactions/index.rst中的官方示例为例，完整流程只有 3 步：

第 1 步：打开文档，创建 Redaction 注释

用createAnnotation("Redact")在页面上创建一个脱敏注释，并通过setRect([x0, y0, x1, y1])指定要擦除的矩形区域。任何与矩形区域接触的文字都会被完全删除。

第 2 步：应用脱敏（最关键的一步）

let annotation = page.createAnnotation("Redact") annotation.setRect([40, 40, 300, 20]) annotation.applyRedaction(true) // true 表示将擦除区域涂黑

注意：Redact注释创建后并不会立即生效，必须调用applyRedaction()，内容才会被真正从文档中提交删除。

第 3 步：保存为新文件

document.saveToBuffer("incremental") // 保存脱敏后的 PDF

至此，敏感文字已经从 PDF 内部结构中永久消失。

定位脱敏区域：搞懂 MuPDF 坐标系

红action 矩形的位置由坐标系决定，这是新手最容易踩坑的地方。MuPDF.js 使用的坐标系与原生 PDF 不同：

• 📐 PDF 坐标系：原点(0,0)在左下角，y 轴向上
• 📐 MuPDF 坐标系：原点(0,0)在左上角，y 轴向下

所以从屏幕像素换算脱敏矩形时，直接用左上角距离即可，无需再做页面高度 - y的转换。可以用page.getBounds()获取页面边界[ulx, uly, lrx, lry]作为换算基准。

批量擦除：page.applyRedactions 一键执行

如果一份文档有多处敏感信息，可以逐页创建多个Redact注释，然后在页面级别统一执行：

page.applyRedactions() // 应用该页上所有脱敏注释

这个页面级 API 适合自动化脱敏管线：先通过文本搜索定位敏感词位置，批量生成红action 矩形，最后一次性applyRedactions()提交。

进阶脱敏：擦除文字之外的隐藏敏感数据

只擦正文往往不够，PDF 里还藏着很多"隐形"敏感信息：作者、创建软件、修改日期等元数据，页面超链接、嵌入式附件、JavaScript 脚本、表单字段值等。

项目自带的示例脚本 examples/tasks/pdf-scrub.ts 实现了一个完整的"深度清理"功能，支持按需开关 10+ 项清理选项（清空元数据、移除链接与附件、清除嵌入文件与 JS、重置表单字段、删除缩略图等），可作为自建脱敏工具的参考模板。

新手常见踩坑清单

坑	现象	解决
忘记调用applyRedaction()	黑条只是个图层，文字仍可提取	创建注释后务必显式应用
矩形没盖住文字基线	部分字符残留	矩形上下边留出文字高度余量
用 PDF 原生的 y 轴换算坐标	擦除区域跑到页面另一头	记住 MuPDF 坐标系原点在左上角

脱敏完成后，建议用page.toStructuredText().asText()再提取一次文本，确认敏感内容已彻底消失——这是最可靠的自检方式。

延伸阅读

• 脱敏官方指南：docs/how-to-guide/annotations/redactions/index.rst
• 深度清理示例：examples/tasks/pdf-scrub.ts
• 完整测试用例：examples/tests/mupdfjs.ts
• 页面操作入门：docs/how-to-guide/page.rst

【免费下载链接】mupdf.jsJavaScript bindings for MuPDF项目地址: https://gitcode.com/gh_mirrors/mu/mupdf.js