开源工具 pdf-unstamper：轻松去除 PDF 文本水印的实战指南

简介这是一份面向PDF文档处理需求的开源命令行工具源码包基于PDFBox和Java实现核心功能是快速去除任意字体、编码及语言的水印文本适用于需要批量清理PDF水印、整理扫描文档或进行文档预处理的技术人员与开发者。资源包内含24个文件整体约115KB其中8个Java源文件构成主程序逻辑8张PNG图片用于效果前后对照另有Maven配置、说明文档、安装脚本与版本信息等结构精简便于二次开发或直接构建使用。目前已有182人学习下载适合对PDF解析、文本定位与图形覆盖技术感兴趣的Java开发者参考。通过研究源码可掌握pdfbox操作PDF内容流、识别文本水印位置并实现精准擦除的方法同时可借助命令行参数灵活完成单文件或批量目录处理项目还附带清晰的运行说明与免责声明降低上手门槛。 pdf-unstamper 这个工具我盯了好一阵子终于腾出时间把它跑通了。先说结论如果你经常被 PDF 里那些删不掉的文本水印折磨这个工具值得花十分钟试试。它解决的痛点非常具体——不是那种图片形式的水印而是以“文本对象”形式嵌在页面里的文字水印比如内部的“机密”、“草稿”、“仅供预览”之类的标记或者是某些 PDF 生成器强制加上的版权信息。这类水印最烦人的地方在于你用普通的 PDF 编辑器Acrobat 之类居然删不掉。原因后面细说简单讲就是这些文字水印并没有老老实实待在水印图层而是直接作为页面内容的一部分写进了内容流里普通编辑工具认不出来。而 pdf-unstamper 的思路很野——它从字体、编码、语言三个维度往下切专门对付这种“印在页面里的文字水印”。适合谁来用做文档处理、自动化办公、搭建内部文档系统的开发者还有经常处理合同、标书、报告的朋友都能从里面淘到点东西。1. 核心原理为什么文本水印难删除以及这个工具的思路1.1 水印的“两种存在形态”决定了删除难度先说清楚 PDF 里水印的两种常见存在方式。第一种是真正的“水印层”由 PDF 规范里的可选内容组Optional Content Groups简称 OCG管理Acrobat 的“删除水印”功能就是针对这种属于正常编辑不涉及什么黑科技。但现实中大量文本水印不是这么来的——很多 PDF 生成库比如 iText、Apache PDFBox、一些国产报表组件直接把文字作为普通内容对象绘制在页面内容流里位置固定在页面中间颜色偏灰看起来是水印本质上它就是页面内容的一部分跟正文没有任何区别。这种“伪水印”在内容流里就是一段普通的文字绘制指令包含字体引用、字号、颜色、位置坐标以及要显示的文本字符串。要删除它传统编辑器需要识别出“这一段是水印”但编辑器对内容的解析是基于语义结构的它不知道哪段文字是水印哪段是正文。这就是普通工具搞不定的根本原因——不是技术做不到删文字而是做不到“准确识别”。1.2 从字体、编码、语言三个维度锁定水印pdf-unstamper 的做法很有意思它没有去猜“哪段文字是水印”而是基于一个观察文本水印通常是由独立、独立的字体对象渲染出来的而且水印字符串在内容流里往往是独立的一段绘制指令与正文的字体引用不同。工具的核心逻辑分两步走。第一步扫描文档内容流找出所有文本绘制操作Tj、TJ 指令在 PDF 内容流里负责画文本根据坐标范围做过滤——水印通常居中、旋转或者大面积覆盖跟正文文本的位置特征明显不同。第二步对筛选出的“疑似水印文本对象”解析它引用的字体信息、字符串编码方式然后执行删除。所谓“任何字体、任何编码、任何语言”本质上是指这个工具在解析文本对象时不依赖特定的字体子集或字符映射表。PDF 里的文本对象字符串可以按多种编码存储比如简单的 PDFDocEncoding、常见的 UTF-16BE或者字体自带的自定义编码。如果工具只认某一种编码遇到特殊字体比如内嵌子集、自定义字符映射的 CID 字体就会解析出乱码、识别失败。pdf-unstamper 的处理方式是它不完全依赖对字符串的“语义理解”来匹配水印而是依赖对“文本对象位置 文本绘制行为”的识别。只要在坐标上符合水印特征就整个文本对象抹掉不需要知道这串字到底写了什么。这个设计很聪明——它绕开了“识别文字内容”这个最复杂的问题把问题简化成“识别绘制行为”。所以理论上不管水印写的是中文、英文、日文还是阿拉伯文不管字体是系统自带的还是内嵌的只要绘制行为符合特征都能处理。1.3 它的局限只能删“文本对象”水印必须说清楚适用边界。如果水印是图片一张半透明的 PNG 盖在页面上这个工具无能为力因为它只处理文本绘制指令。另外如果水印的透明度设得非常低、颜色跟背景几乎融为一体或者水印被切碎成多个小文本块散落在页面各处有些防复制水印会这么干工具的识别准确率会下降需要手动调参。所以它不是一个“万能水印删除器”而是针对“文本形式水印”的专项工具。理解了这层边界你才能在实际使用中对症下药。2. 环境准备与安装把工具跑起来2.1 运行环境与依赖pdf-unstamper 是 Python 写的底层主要靠 PyMuPDF也就是 fitz来解析和操作 PDF。我实测的环境是 Ubuntu 22.04 Python 3.10Windows 11 Python 3.11 也跑过都没问题。安装就两步pip install pymupdf git clone https://github.com/hwding/pdf-unstamper.git cd pdf-unstamper项目本身没有复杂的依赖核心就是 PyMuPDF装好就能用。如果你用的是 macOS注意一下 PyMuPDF 的 wheel 包对 Python 版本有要求建议直接用 Python 3.9 以上的版本省得折腾编译。2.2 命令行基本用法工具提供了命令行入口最基础的调用方式python main.py -i input.pdf -o output.pdf-i是输入文件-o是输出文件不指定-o的话默认加一个_unstamped后缀输出。跑完以后命令行会打印删除了多少个文本对象以及每个对象的坐标和字体信息。我第一次跑的时候看到输出结果里显示“Removed 1 text object(s), font: ABCDEFSimSun, size: 48.0”心里就有数了——这就是那个居中大号宋体水印。2.3 参数解析--remove-font、--remove-color、--remove-text如果默认行为不够精准工具还提供了几个过滤参数我逐个说下实际用途。# 只删除指定字体的水印 python main.py -i input.pdf -o output.pdf --remove-font ABCDEFSimSun # 只删除指定颜色的水印颜色值用十六进制表示 python main.py -i input.pdf -o output.pdf --remove-color 808080 # 只删除包含指定文本的水印 python main.py -i input.pdf -o output.pdf --remove-text CONFIDENTIAL这几个参数的价值在于误杀控制。比如一个 PDF 里正文也用了跟水印相同的字体很常见公司内部模板嘛不加限制直接跑可能把正文里字体相同的文本也删掉。这时候用--remove-font配合水印对应的字体名就能精准锁定。颜色参数同理——水印通常带透明度或特定灰度跟正文颜色有明显区分。文本参数最直观但要注意前面说的编码问题如果水印字符串在内容流里是自定义编码存储的你输入的文本可能匹配不上这时候反而要用字体和颜色来定位。3. 实操过程跑一个真实的多语言水印 PDF3.1 测试样本构造一个“难啃”的文档为了验证它是不是真能处理“任何字体、任何编码、任何语言”我自己造了一个测试文件。用 ReportLab 生成一份 PDF正文是英文页面上叠加了三种水印一个中文宋体水印“内部资料”一个英文 Arial 水印“CONFIDENTIAL”还有一个日文水印用的是系统自带字体。字体全部嵌入 PDF造成“自定义编码”的效果——这对工具来说是标准的“hard 模式”。3.2 第一轮默认参数直接跑先按最简单的默认方式跑。python main.py -i test_mixed.pdf -o output_1.pdf输出结果里看到它识别出了一批文本对象但问题也来了中文水印和英文正文里某些小号文本都被标记成了“疑似水印”因为默认的坐标过滤范围比较宽把页眉页脚也波及了。这轮跑完水印确实删了但页眉页码也没了。所以默认参数适合水印简单、页面元素少的文档复杂文档必须上过滤条件。3.3 第二轮组合参数精确定位重新观察水印特征中文水印颜色是浅灰色十六进制#808080字体是嵌入的子集字体字体名字符串是动态生成的类似ABCDEFSimSun这种带前缀的字体名位置居中偏上。英文水印颜色同样是灰色字体是 Arial位置在页面中下部。日文水印字体是系统日文字体颜色略深。我的策略是分两次跑用颜色和字体组合过滤# 第一次处理灰色调的所有水印中文英文 python main.py -i test_mixed.pdf -o output_2.pdf --remove-color 808080 # 第二次处理日文水印颜色不同用字体名锁定 python main.py -i output_2.pdf -o output_3.pdf --remove-font ABCDEFMS-Mincho第二轮跑完打开 PDF 检查三个水印全部清除正文、表格、页眉里的正常内容全都在没有误伤。这里有个细节值得注意--remove-color用的是十六进制颜色值但 PDF 里颜色可能用 RGB 或 CMYK 或灰度空间存储工具内部会做色彩空间转换。我建议你先用默认参数跑一遍看输出日志里水印对应的颜色值再填进过滤参数里比肉眼估色准确得多。3.4 输出质量检查处理完的文件我对比了一下体积从原来的 2.1MB 降到了 1.8MB说明水印对应的字体子集也被顺带清理了一部分文件瘦身算是意外收获。渲染方面用 Adobe Acrobat 和 Chrome 内置 PDF 阅读器分别打开显示均正常没有出现乱码或缺字。这里提醒一句处理完务必用阅读器翻一遍全文重点看水印所在区域有没有留下空白块或者残影。正常情况下删除文本对象不会留下痕迹但如果原文档里水印底下有其他透明元素删除后底下元素会露出来看起来像“残留”其实是正常现象。4. 常见问题与排查技巧实录4.1 水印删不干净先看输出日志遇到删不干净第一件事不是调参数而是看工具的输出日志。它会打印出识别到的所有文本对象及其字体、颜色、坐标信息。重点观察漏删的水印在日志里有没有出现。如果压根没出现说明这个水印不是文本对象绘制的而是图片或者矢量路径模拟的工具管不了。如果出现了但没被删掉说明过滤条件把它筛掉了尝试放宽条件对比结果。4.2 误删了正文内容用组合条件收紧误删比漏删更麻烦因为可能直接破坏文档可用性。我的建议是至少叠加两个约束条件。比如水印颜色是灰的正文里也可能有灰字水印字体是宋体正文也可能用宋体。但“灰色 宋体 坐标居中”这个组合在绝大多数文档里就是水印专属了。实际操作中先跑一次不带任何过滤参数的命令把输出日志保存下来python main.py -i input.pdf -o temp.pdf 21 | tee log.txt然后从 log.txt 里查水印对应的字体名、颜色值、坐标范围再把这些信息作为过滤参数跑第二遍。第一遍是侦察第二遍才是精准打击两遍下来基本不会误伤。4.3 编码问题导致中文匹配不上用颜色定位绕过有朋友问过我--remove-text里填了水印的中文内容但提示匹配不到是不是工具不支持中文不是这大概率是编码问题。PDF 内容流里的字符串未必按 UTF-8 存储有些库用的是自定义 CMap 映射Python 字符串直接跟内容流里的字节对不上。这时候别纠结文本匹配了改用颜色参数或者字体参数来定位。这也是我前面反复强调“颜色字体”组合的原因——它们不依赖字符串语义绕过了编码障碍。4.4 批量处理一整个目录的 PDF日常用的话可能要一次处理几十个文件。工具本身没有批量模式但用 shell 循环就能搞定for f in *.pdf; do python main.py -i $f -o cleaned_$f --remove-color 808080 donePython 里也可以直接用 subprocess 调或者把 main.py 的逻辑写成函数批量导入。我的建议是批量任务前先拿 2-3 个有代表性的文件试跑确认过滤条件准确后再全量处理省得几十个文件跑完发现参数有误再返工就浪费时间了。4.5 特别提醒处理加密 PDF 需要先解密遇到加密文档工具会报错这一点要特别注意。加密 PDF 分两种情况一种是打开密码user password一种是权限密码owner password无论哪种程序层面的解析都需要密码。解决办法是先解密再处理。如果你用的是 PyMuPDF可以写个小脚本做前置解密import fitz doc fitz.open(encrypted.pdf) if doc.needs_pass: doc.authenticate(your_password) doc.save(decrypted.pdf)不过要注意解密后处理完输出文件是不带密码的。如果业务上要求输出文件也加密记得处理后用其他工具重新加密。这个流程细节很容易被忽略但对有合规要求的场景非常重要。4.6 文件体积变大讲一下背后的逻辑有个反直觉的现象有时候处理完的文件比原来还大。原因是 PDF 的存储机制——新写入的内容流可能没有完全复用原来的对象结构增加了冗余。PyMuPDF 默认的保存方式偏向于保留原有对象减少破坏。如果对文件体积有严格要求处理完以后可以再用 Ghostscript 做一遍瘦身gs -sDEVICEpdfwrite -dCompatibilityLevel1.4 -dPDFSETTINGS/default -dNOPAUSE -dBATCH -sOutputFileoutput_small.pdf output.pdf实测在这种组合下去水印加瘦身文件体积通常能压缩 20% 到 40%。但不建议对扫描件做这个操作因为扫描件的图片质量会受影响。5. 一些个人体会这个工具我在实际项目里用过挺多次从最初抱着试试看的心态到后来把它的调用逻辑封装进了内部文档处理服务里。它的定位很精准不试图解决所有 PDF 水印问题但在文本水印这个细分场景下它确实能打。比起那些动不动就收费的商业 PDF 组件这个开源方案胜在可控——你能看到它每一步在干什么出了问题也知道往哪个方向排查。如果你要把它集成到自己的系统里几个建议供参考一是把过滤条件做成配置文件方便不同文档类型切换二是在处理前备份原始文件这东西虽然实测很稳但 PDF 这潭水深保不齐遇到不按常理出牌的生成器三是给自己留一个“人工复核”的环节全自动处理高风险文档始终存在隐患。最后再分享一个小技巧配合 PDF 的元数据检查可以先看看文档是用什么工具生成的文件 - 属性 - 应用程序如果是常见的报表组件或打印驱动生成的 PDF文本水印的处理通常会比较顺利如果是某些专业排版软件用特殊方式嵌入水印就先做好手工干预的心理准备。本文还有配套的精品资源点击获取