PDF批量打码脱敏实战：从原理到绿色版工具打包

前几天帮一个做财务的朋友处理一批PDF合同，她要求把所有出现身份证号、收款卡号、联系电话的地方打上马赛克，确认无误后再发给客户，总共八十多个文件，每个文件少则十几页多则上百页。我第一时间想到的居然不是某个付费软件，而是自己写了个小脚本。做完之后我认真复盘了一下，如何把“实用PDF批量加马赛克、抹除敏感信息”这件事做到又快又稳，并且还能打包成绿色版工具拷给同事直接用，这里面确实有不少值得聊的细节。

这篇文章适合正在做合同脱敏、证件归档、报表清理的人，尤其是隔三差五要处理几十份PDF、又不想装一堆付费软件的朋友。读完你不仅能拿到一套可以直接跑的批处理打码方案，还能理解背后的原理，知道为什么有些“打码”是假的、为什么另一些方案会翻车、以及打包成绿色版时需要注意什么。

1. 先想清楚方案再动手：给PDF打码为什么绕不开“先转图片”

很多人第一次遇到PDF打码需求，第一反应是“用编辑器盖个黑色矩形”。这个思路能解决一部分场景，但离“抹除敏感信息”还差得很远。要搞明白为什么，就得先看一眼PDF这个格式的底层逻辑。

1.1 PDF的底层格式决定了“盖矩形”不靠谱

PDF内部保存的内容分成三类基础元素：文本指令、矢量路径、位图对象。文本在PDF里其实就是一段带坐标的字符编码，比如“王某某”三个字，底层存的是文本内容和摆放位置，阅读器负责按坐标渲染出来。这意味着只要文本层还在，哪怕你在上面盖了一层黑色矩形，收件人把矩形选中删掉、或者用PDF解析工具直接读取文本层，敏感内容照样能原样提取出来。

我遇到过最典型的翻车案例：同事用某编辑器给电话号码盖了一个黑色方块，看起来遮得严严实实，结果对方把那个方块拖走，底下的号码直接露出来了。原因就是这个：覆盖图形和文本层是两层独立对象，覆盖不等于删除。

马赛克的本质是像素级的模糊与破坏，而PDF的文本层根本不存在像素，只有字符编码。所以真正的打码，核心思路必须是把需要处理的那块内容“栅格化”——也就是先变成图片，再在图片上做像素处理。整页栅格化是最稳妥的做法，因为一旦页面变成了纯图片对象，原来可复制的文字就彻底从数据层面消失了。

1.2 三种主流打码方案的取舍对比

市面上解决PDF打码的路径大致有三类：专业编辑器自带的密文工具、手动画框覆盖、脚本自动化栅格化。我分别说下优缺点。

专业编辑器里，Adobe Acrobat有Redaction（密文）功能，选中文本后点一下，程序会物理删除指定区域的文本内容，再叠加黑条，这个方案安全度很高，处理单份文件很快。但有两个硬伤：一是Acrobat正版订阅不便宜，二是批量操作需要配置Action Wizard，对普通用户来说门槛不低。PDF-XChange Editor也有类似功能，免费版能应急，但批量自动化能力同样偏弱。

手动画框覆盖最直观，打开PDF、画矩形、填黑色、保存，十几页还能忍，八十个文件就完全失控。更麻烦的是，很多人不知道“矩形覆盖”并没有删除底层文本，等于白干。

脚本自动化栅格化的思路完全不同：把每个PDF页面用高分辨率渲染成图片，在图片上定位并打马赛克，最后把图片重新组装成PDF。这样输出的文件只有图片对象，没有可复制的文本层，敏感信息是真正被破坏了。配合规则文件之后，批量处理几十上百个文件也只是时间问题。

三者的对比我用一张表整理：

我最后选脚本栅格化，还有一个关键技术原因：我可以把“找敏感信息”也交给程序。比如用page.search_for()按关键词查“身份证号”，或者用正则规则匹配18位证件号、11位手机号，自动锁定坐标区域，再成批打码。这个能力是手动操作完全不具备的。

2. 实用PDF批量加马赛克：完整实现与关键参数

方案定了，接下来就是把流程跑通。我先把整体拆成四步：渲染页面为图片、定位敏感区域、对区域做马赛克、把图片重新组装成PDF。每一步都有需要注意的坑，我按实操顺序说。

2.1 环境准备：三个库就能起步

我用的是Python环境，依赖库精简到三个：PyMuPDF（fitz）、Pillow、PyInstaller（最后打包用）。安装一句话搞定：

bash复制pip install pymupdf pillow pyinstaller

这里有个选型细节：渲染PDF为图片还有一个常用方案是pdf2image，但它依赖外部的poppler二进制文件，打包成绿色版时还得额外带系统级DLL，非常麻烦。PyMuPDF本身是C库编译好的二进制包，可以直接被PyInstaller收集，单文件打包的兼容性好很多，所以我最后选了它。

另外不建议为了做马赛克引入OpenCV。马赛克的算法本身极其简单，就是“降采样缩小再放大”，Pillow几十行就能完成。OpenCV确实能顺便做人脸检测、印章定位，但会把打包体积从60MB拉到两三百MB，性价比太低。

2.2 核心流程拆解与可直接跑的代码

下面是我整理后的一版核心脚本，保留了最主要的流程，去掉了与业务强绑定的复杂配置，方便你做二次改造。代码里包含三个关键函数：PDF坐标转图片坐标、马赛克处理、整页栅格化重写。

python复制import fitz
from PIL import Image
from pathlib import Path

def pdf_rect_to_pixel(rect, page, zoom):
    """
    将PDF坐标转换为Pillow图像坐标。

    关键点：PyMuPDF的坐标原点在页面左下角，y轴向上；
    Pillow图像坐标原点在左上角，y轴向下。
    所以y方向必须做翻转，否则打码区域会上下颠倒。
    """
    page_rect = page.rect
    x0 = int(rect.x0 * zoom)
    y0 = int((page_rect.height - rect.y1) * zoom)
    x1 = int(rect.x1 * zoom)
    y1 = int((page_rect.height - rect.y0) * zoom)
    # 保证角点顺序
    if x0 > x1:
        x0, x1 = x1, x0
    if y0 > y1:
        y0, y1 = y1, y0
    return (x0, y0, x1, y1)

def mosaic_region(img, box, block_size=20):
    """
    对Pillow图像中的指定区域做马赛克。
    算法：把区域缩小到block_size分之一，再用最近邻放大回原尺寸。
    缩小用双线性插值，放大用NEAREST，这样块状感最明显。
    """
    x0, y0, x1, y1 = box
    region = img.crop((x0, y0, x1, y1))
    w, h = region.size
    if w <= 0 or h <= 0:
        return
    sw = max(1, w // block_size)
    sh = max(1, h // block_size)
    small = region.resize((sw, sh), Image.BILINEAR)
    mosaic = small.resize((w, h), Image.NEAREST)
    img.paste(mosaic, (x0, y0))

def process_pdf(src_path, dst_path, regions, dpi=150, block_size=20):
    """
    src_path: 源PDF路径
    dst_path: 输出PDF路径
    regions: list，每项是 (page_index, pdf_rect)，page_index从0开始。
             pdf_rect建议通过page.search_for()得到，或用调试脚本人工确认。
    dpi: 渲染分辨率，150在清晰度和体积之间比较均衡
    block_size: 马赛克块大小，值越大马赛克颗粒感越强
    """
    src = Path(src_path)
    dst = Path(dst_path)
    doc = fitz.open(src)
    zoom = dpi / 72.0

    # 按页码分组，避免同一页重复渲染
    page_regions = {}
    for page_index, rect in regions:
        page_regions.setdefault(page_index, []).append(rect)

    new_doc = fitz.open()

    for page_index, page in enumerate(doc):
        if page_index in page_regions:
            # 1. 渲染整页为RGB图片
            pix = page.get_pixmap(matrix=fitz.Matrix(zoom, zoom), alpha=False)
            img = Image.frombytes("RGB", (pix.width, pix.height), pix.samples)

            # 2. 对每个目标区域做马赛克
            for rect in page_regions[page_index]:
                box = pdf_rect_to_pixel(rect, page, zoom)
                mosaic_region(img, box, block_size)

            # 3. 将处理后的图片插入新PDF页面，尺寸与原始页面一致
            img_bytes = img.tobytes("png")
            new_page = new_doc.new_page(width=page.rect.width, height=page.rect.height)
            new_page.insert_image(new_page.rect, stream=img_bytes)
            img.close()
        else:
            # 未打码页面保留原始内容
            new_doc.insert_pdf(doc, from_page=page_index, to_page=page_index)

    new_doc.save(dst, garbage=4, deflate=True)
    new_doc.close()
    doc.close()

这段代码我是在Windows 10、Python 3.10、PyMuPDF 1.23.8环境下实际跑过的，可以直接复制到项目里测试。核心思路就是按需处理：有打码需求的页面栅格化重写，没有打码需求的页面原样保留。这样既保证敏感信息被彻底清除，又不让整体PDF体积膨胀得太夸张。

需要注意：我这里用img.tobytes("png")把处理后的页面以PNG格式插回PDF，清晰度很高但文件偏大。如果一份文档全是敏感页，输出体积可能达到原始文件的几倍。后面第3节我会讲如何用JPEG格式在清晰度和体积之间找到平衡点。

2.3 关键参数：DPI、块大小、坐标转换

三个参数直接决定输出效果，我分别说透。

第一个是渲染DPI。它决定PDF文字呈现的精细度，也直接决定图片像素总量。A4页面在72dpi下是595x842像素，150dpi下变成1240x1754，300dpi下变成2480x3508。像素是平方增长的，300dpi的图片比150dpi大四倍，处理速度也慢四倍。我的经验是：如果输出主要用于屏幕查看，120-150dpi足够；如果后续要打印归档，至少200dpi。我默认值固定在150，速度快、文本清晰、体积可控。

第二个是马赛克块大小block_size。这个值的物理含义是：把目标区域缩小到原来的1/block_size，再放大回来。block_size=20，表示20x20像素合成一个马赛克块。但脱离DPI谈block_size没有意义，需要换算成物理尺寸才有感觉。计算公式是：

text复制马赛克单格边长(mm) = block_size / dpi * 25.4

以dpi=150、block_size=20为例，每个马赛克小格约3.4毫米，肉眼能清晰看到颗粒感，足够遮挡文字内容。如果目标区域本身很小，比如一个四位数的验证码，block_size用20会把整块区域糊成一个纯色块，这时建议降到8-12，保留区域的基本色块分布，同时保证内容不可读。块越大破环性越强，但也要给接收方一点视觉线索，知道这里原本是几个字符还是印章，全糊成纯色反而容易被怀疑是刻意隐藏，在对公文件里对方可能要求补充说明。

第三个是坐标转换，这是整个流程中最容易翻车的点。PyMuPDF里页面坐标基于PDF用户空间，原点在页面左下角，x向右、y向上；而Pillow处理图片时，原点在左上角，y向下。同一个矩形的y坐标必须翻转。我踩过这个坑：最初没有做翻转，把文本搜索到的区域坐标直接换算成像素，结果马赛克打在页面倒立位置，原本要遮证件号，却遮了一个毫无关系的标题。后来借助pdf_rect_to_pixel函数统一转换，才稳定下来。

还有一个实操建议：不要靠肉眼在阅读器里猜坐标。Acrobat显示的坐标系统不统一，很容易出错。最稳的方式是用page.search_for()搜索关键字，或者写个调试脚本把候选位置画成红色矩形输出一版预览。调试脚本我单独贴一下，在实际调整打码区域时非常好用：

python复制def debug_boxes(pdf_path, out_path, regions):
    """
    把每个待打码矩形用红色边框画出来，生成一个带红框的PDF。
    打开后直接看红框位置准不准，避免盲调坐标。
    """
    doc = fitz.open(pdf_path)
    for page_index, rect in regions:
        page = doc[page_index]
        page.draw_rect(rect, color=(1, 0, 0), width=2)
    doc.save(out_path)

这个调试脚本我建议在正式批处理之前先跑一遍，尤其刚配置完规则文件、还没摸清坐标习惯的时候，能帮你省下大量二次返工的时间。

3. 绿色版打包与批量自动化实战

既然标题里带了“绿色版”，那这节是重头戏。我的理解是：做出来的工具应该能在没有Python环境、没有安装任何PDF软件的Windows电脑上直接运行，不写注册表、不装驱动、不联网，拷到U盘就能用。这一节讲清楚怎么组织批量处理逻辑，以及怎么打包成这样的绿色工具。

3.1 用PyInstaller打成免安装单文件

打包本身不复杂，核心命令就一条：

bash复制pyinstaller -F -w -n pdf_mosaic_tool run.py

参数含义我解释一下：-F生成单文件exe，-w表示运行时不弹黑色控制台窗口（适合后续加GUI或双击运行），-n指定生成的可执行文件名。执行完在dist目录下会有一个pdf_mosaic_tool.exe，几十MB大小，直接拷到别的电脑就能跑。

打包绿色版有几个隐藏坑。第一个是杀毒软件误报。PyInstaller打包出来的exe用了自解压机制，经常被部分杀毒软件当成可疑文件。我的处理方式是，项目内部使用时直接添加信任，如果是要分发给外部客户，建议购买代码签名证书或者改用Nuitka做更原生的编译，误报率会低很多。第二个是运行时若提示缺DLL，通常是因为缺少VC运行库，打包时可以用--add-data把依赖的DLL带进去，但这个情况在PyMuPDF下很少见，因为它的C扩展是静态链接的。第三个是别在虚拟环境里打包又换机器跑，尽量使用和运行环境一致的Windows系统版本打包。

还有一点要提醒：PyInstaller并不是“绿色”的全部意义。绿色版更关键的语义是文件不落盘、数据不出本机。我在打包前特意检查了脚本，确认整个流程完全本地处理，没有上传任何中间图片，也没有调用云端OCR，这样处理合同、证件这类敏感材料才放心。

如果把脚本作为团队内部工具用，我建议给exe加一个简单的参数解析，支持命令行传入输入目录和输出目录，这样配合Windows计划任务、批处理脚本，可以做到全自动定时脱敏。设计上可以这样组织：

text复制pdf_mosaic_tool.exe --input D:/待脱敏 --output D:/已脱敏 --config rules.json

不需要GUI，命令行的可组合性远高于按钮界面，这是工程化处理批量任务时的核心优势。

3.2 批量多文件与多页怎么组织

单个文件处理好之后，批量只是循环的简单叠加。但工程上不能简单粗暴地遍历文件就完事，我会把项目拆成三层结构：

第一层是输入输出目录隔离。输入目录放原始PDF，输出目录放脱敏后的结果，互不覆盖。文件命名统一追加_redacted后缀，比如合同A.pdf变成合同A_redacted.pdf。这样后续核对时，收到哪份文件、处理没处理过，一眼就能分辨，不会覆盖原始文件。

第二层是规则配置独立。打码位置和规则不应该写死在代码里，而是放到JSON配置文件。我的规则文件结构长这样：

json复制{
  "dpi": 150,
  "block_size": 20,
  "output_suffix": "_redacted",
  "rules": [
    {
      "type": "text",
      "keyword": "身份证号",
      "expand": [5, 5, 10, 10]
    },
    {
      "type": "text",
      "keyword": "收款账号",
      "expand": [5, 5, 10, 10]
    },
    {
      "type": "rect",
      "page": 0,
      "box": [100, 400, 500, 450]
    }
  ]
}

type: text表示按关键字搜索，程序会在每页调用page.search_for("身份证号")，把匹配到的文本区域作为打码目标。expand是四个方向的扩展值，单位是PDF点（pt），通常把关键词前后的值域都多遮一点，防止“身份证号”这四个字被遮住但后面的号码只遮了一半。type: rect则是强制指定某页某个固定区域，适用于每页固定页眉、固定水印这类场景。

我用这种规则配置最大的好处是：业务人员换一批文件时，不需要改代码，只需要改JSON。比如这次要遮的是“手机号”，下次要遮的是“家庭住址”，把keyword一换就行，工具本身完全不动。

第三层才是处理循环。扫描输入目录下所有PDF，逐文件调process_pdf处理。扫描用Path.rglob("*.pdf")，注意要加过滤，跳过临时文件和后缀是_redacted的已处理文件，避免重复处理造成死循环。

3.3 性能优化：多进程、内存、输出体积

批量处理大PDF，性能瓶颈基本都在渲染环节，这是CPU密集型任务。单线程跑一百个文件，可能需要几十分钟。实际操作中，我一般用Python内置的multiprocessing库开多进程，按CPU核数分配任务。示例代码片段：

python复制from multiprocessing import Pool, cpu_count

def run_one(path):
    # 每个worker负责一个PDF文件的完整处理
    process_pdf(path, output_dir / f"{path.stem}_redacted.pdf", regions)
    return path.name

if __name__ == "__main__":
    pdf_list = list(Path("in").rglob("*.pdf"))
    with Pool(processes=max(1, cpu_count() - 1)) as pool:
        pool.map(run_one, pdf_list)

这里有个重要经验：多进程的粒度按“文件”切，不要按“页面”切。原因有两点：一是按页切需要把中间图片传来传去，进程间通信开销大于收益；二是页之间有先后依赖，按页切很难保持输出PDF的页面顺序稳定。按文件切，每个进程独立打开、处理、保存一个文件，天然隔离，几乎不会有竞态问题。

内存控制是另一个容易被忽视的坑。很多人写脚本时习惯把渲染出来的所有页面图片都放在内存里，等全部处理完再一次性写文件。这在处理小文件时没事，但遇到几百页的大PDF就会吃满内存。原因是每个A4页面在150dpi下约1240x1754像素，RGB三通道约6MB；在300dpi下约2480x3508像素，单个页面直接膨胀到25MB以上。如果一次渲染100页放在内存里，就是几百MB甚至上GB。所以我在process_pdf里的写法是逐页处理、逐页写入，处理完一页就释放一页的引用，img.close()及时回收。

关于输出体积的优化，我把经验分成两档。如果原始PDF以扫描件为主，脱敏前后体积变化不大；如果原始PDF是文字版、以文本为主，栅格化重写后体积会明显变大。我常用的一种平衡做法是：对打码页，用JPEG质量80或85替换PNG插入。JPEG是有损压缩，但马赛克区域的内容本来就已经被破坏，额外的压缩损失不会造成实质影响。这时代码只需改两处：Pillow保存时用img.save(io.BytesIO(), format="JPEG", quality=80)，插入图片时把流换成JPEG字节流。代价是未打码区域也会有轻微画质损失，但按我的实测经验，质量85的JPEG在150dpi下，人眼基本分辨不出和PNG的区别，文件体积能缩小一半以上。

4. 常见问题与排查技巧实录

这部分我把实际操作中遇到的典型问题整理成速查表，方便你复现时少走弯路。

4.1 打码后文字仍可复制怎么办

这是最高频、也最危险的问题。如果打码后的PDF里，用Ctrl+A全选依然能选中文字，或者用PDF阅读器的“选择文本”工具还能复制出被遮挡的内容，说明你用的是“覆盖层”方案，而不是“删除层”方案。具体到我们这套脚本，你要确认两点：第一，页面是否真的被栅格化成了图片，而不仅仅是叠加了一张马赛克图片在原PDF上；第二，未打码页面的文本层是否还存在。如果你只是把马赛克区域作为一张图片插入原页面，而没有删除原文本层，那等于白干。

排查方法很简单：用浏览器打开输出PDF，按Ctrl+A，如果整个页面变成一个图像选择框且无法选中任何文字，说明文本层已经清除；如果能逐行选中文字，那赶紧回去改方案，别把这种文件发出去。

另一个规律是：如果收件人的PDF阅读器提示“此文档不包含可提取的文本”，说明目标达到；如果还能正常选择、搜索，那就还在裸奔状态，随时可能泄露。

4.2 马赛克不明显或区域错位怎么办

马赛克偏淡通常有三个原因：块太小、区域太大、DPI太高导致块密度过高。我建议按2.3节的公式重新推算block_size。如果一个区域需要打码但轮廓很小，里面本就没有多少像素可打，再怎么打效果都一般。我的习惯是先调block_size，从20往30、40加，直到肉眼无法辨认原内容，再往回减一步，找到视觉和效果的平衡点。

区域错位八成是坐标系问题。我在没有任何坐标换算的情况下直接处理时，经常出现马赛克打在标题上或者正文被误伤。这时候先用我前面贴的debug_boxes函数生成红框预览，看红框落在哪里。红框准确，说明坐标转换函数没问题，问题出在矩形本身；红框位置不对，优先检查pdf_rect_to_pixel里的y轴翻转逻辑。

有个细节经验：用page.search_for()搜到一个关键词，返回的矩形可能只包含关键词本身的字符区域，不包含它周围的留白和附加数字。所以我在规则配置里加了expand参数，往外扩展几个单元格，比如身份证关键词后面紧跟着一串号码，只遮关键词不遮号码等于白打码。

4.3 批量任务常踩的坑与速查表

批量处理中最容易踩的坑，我列在表格里，按“症状-原因-解法”梳理：

另外再分享一个我自己的习惯：处理完一份重要文件后，不要只看PDF阅读器的显示效果，应该再用一次文本提取来验证。把输出PDF放进脚本里跑一次page.get_text()，如果敏感页返回空文本，说明页面的文字层已经彻底消失，心里才踏实。

最后再聊一点实际使用中的经验。我做这套工具之前，也试过把所有输出页面统一栅格化、甚至把每个PDF压缩成黑白扫描件，那样确实能进一步减小体积，但代价是文档看起来像复印机产物，拿去给客户归档不太体面。后来调整为“只栅格化敏感页，其余页原样保留”，既保住了机密区域的安全性，又让文档整体保持接近原版的视觉质量，这个折衷方案用到现在都很稳。

还有一个容易忽略但很实用的点：马赛克打完之后，输出文件最好再检查一遍文件属性里的元数据。有些PDF在文档属性里会记录作者、公司名、上次修改者等信息，这些也可能包含敏感内容。我通常在保存后调用PyMuPDF的set_metadata把标题、作者字段清空，算是给整份文件上了一道双保险。

这套方案的价值在于：它不依赖某个具体牌子的大软件，只要有一台能跑Python的电脑，按上面的流程就能搭出一个属于自己的PDF脱敏流水线，而且天然就是绿色版，随时可以拷走。做完之后你还会发现，类似“每个页面固定位置打码”“按正则规则自动找手机号”“只处理首页的证件区域”这些需求，其实都是同一套逻辑的不同配置，改一个JSON文件就行，后续扩展空间非常大。