上午刚把一个批量添加PDF文本水印和图片水印的小工具跑完最后一批用例正好借这篇聊聊它的设计过程。这个工具内部代号863功能一句话就能说清把一批PDF丢进输入目录按配置给每一页打上文本水印比如内部编号、部门名称、日期或者图片水印比如Logo、签名图再统一输出到另一个目录。听起来简单但真正做起来牵扯到字体、旋转、透明度、批量并发、加密文件兜底这些事每一件都能卡住半天。这篇把整个方案从头拆到尾包括为什么选择PyMuPDF、参数怎么定、批量怎么跑、生产环境怎么避坑。如果你也负责给大量PDF加版权标识、追溯信息或者品牌Logo这篇文章可以直接照着落地不必再走我踩过的那一圈弯路。1. 这工具解决什么问题批量水印的真实使用场景1.1 手动加水印为什么让人崩溃大多数人第一次接触PDF水印是在某个需要发合同的下午。打开编辑器点添加水印输入文字调字体预览保存。第一个文件还算新鲜做到第三个开始烦躁做到第十个基本就在怀疑人生。如果手头是五十份合同、二十份方案、三十页讲义光是重复打开关闭文件一天时间就这么耗没了。更麻烦的是手动操作很难保证一致性。今天这个水印位置偏上了明天那个字号调小了后天又有人说Logo颜色太淡。如果公司在做文件分级管理不同部门、不同密级要盖不同的水印文字手动改一百个文件很难确保某个编号没有漏改、没有复制错。批量工具的价值恰恰体现在这种高频、重复、必须全部一致的场景里它把“给PDF加水印”从一个手动动作变成了一条配置文件驱动的批次任务。我还遇到过一个更极端的场景A同学负责给一百多份培训资料加公司Logo水印原计划半天做完结果做到第三十份时眼睛已经花了有四份文件的水印位置错了交付之后被讲师点名问“为什么这几份不一样”。这种错误完全是重复劳动带来的不是细心就能彻底解决的。工具化之后只要配置一致一百份和一千份的水印位置就完全一致。1.2 文本水印和图片水印分别解决哪几类诉求文本水印和图片水印在实用场景里有明显分工先想清楚需要哪种再决定工具怎么配置。我用一张表把两者的区别列出来维度文本水印图片水印内容类型编号、名称、日期、密级等动态信息Logo、签名、底纹等固定视觉元素生成成本低改一行配置就能批量换内容高需要先准备素材文件典型用途内部文件溯源、防截图外泄、标识归属对外品牌展示、防止盗图冒认、视觉调性批量优势内容可自动组合适合大规模生成适合全量平铺或固定角落展示对阅读的影响需要控制密度、颜色和角度需要控制缩放比例和透明度实际项目里两种水印经常混用。比如某团队给销售发产品方案全篇铺上“内部资料”文本水印封面右上角再盖一个半透明品牌Logo图片水印。文本水印负责追溯泄露源头图片水印负责品牌展示各司其职。所以在做863工具时我坚持把两条功能线分开实现而不是混在一个逻辑里这样后续扩展和维护都更清晰。1.3 “批量”的两个维度以及一个隐含前提“批量”这个词很多人理解成“多文件处理”但落到实现上至少要覆盖两个维度。维度一是多文件输入目录下有几十或上百个PDF逐个处理。维度二是多页一个PDF几百页每页都要打上水印。如果只处理了多文件遇到几百页的标书还是会卡在单文件上如果只处理了多页上百个小文件还是要手动遍历。863在这两个维度上是同时覆盖的对外用并发调度处理多个文件对内对每个文件的每一页执行渲染。还有一个隐含前提是“可重入”。批量工具必须保证同样一批输入只要配置不变无论跑多少次水印的位置、内容、样式都完全一致。这样出了问题才好追溯“是哪一批哪一次生成的配置是什么”。我在工具里把输出目录按日期和时间命名文件名保留原名但加后缀同时把本次运行的配置复制一份到输出目录事后查起来清清楚楚不会出现“这文件到底什么时候处理的、用的什么参数”的谜案。2. 方案选型PDF水印实现路线怎么走2.1 加一个水印其实是在PDF上加什么新手容易有一个误解觉得给PDF加水印和给图片加水印一样是把像素改了。但PDF本质上是一堆对象描述不是一张平面图。加文本水印本质是在每一页的页面对象流里插入一段绘制文字的指令加图片水印则是引入一个图像对象并在页面上按指定矩形区域绘制它。这个认知决定了一条关键原则水印不破坏原文档里的正文内容。正文的文字、排版、超链接、书签都保留只是视觉上多了一层水印。正因为这样加水印比“把PDF转成图片再糊一层”要好得多。后者会把文字变成位图导致无法复制、无法搜索文件体积还会暴涨。拿书来类比会更直观PDF是一本印好的书水印相当于在每一页上贴一张透明便利贴正文没有被擦掉只是多了一层标记。所有的技术选型都应该围绕“不破坏原文档结构”这个前提展开。2.2 三条实现路线的对比与选择动手前我对比过三条技术路线各有适用场景。第一条是水印PDF合并。先做一个只有水印的PDF再和原PDF一页一页合并。这种方式代码简单但合并后会产生多余的页面对象而且很难对某一页做差异化位置调整适合临时应急不适合做成工具。第二条是直接操作PDF底层对象流。在页面树里插入内容流指令这是最接近PDF规范的做法但用底层语法写起来非常繁琐而且不同PDF结构的兼容性要自己处理基本只适合研究协议的人。第三条是基于现成库调用页面绘制接口。用PyMuPDF这类库在page对象上直接插文字、插图片设置旋转角度、颜色、缩放。它本质上还是在写PDF内容流但库把底层细节封装好了代码量小兼容性也经过大量真实文件验证。863选择的是第三条路线。除了PyMuPDF我还评估过reportlab和pypdf。reportlab的强项是从零生成PDF修改已有PDF反而别扭pypdf擅长拆分合并、加密解密但绘制能力很弱。真正想做一个好用、可维护的水印工具PyMuPDF是当前Python生态里性价比最高的一档。整个评估过程用了大概半天但省下的调试时间远超半天。2.3 模块划分文本线、图片线、调度线863没有做成一个大而全的GUI而是拆成三条边界清晰的模块线。文本线负责把配置里的文字内容渲染到页面只关心字体、字号、颜色、角度、位置和间距。图片线负责把PNG或JPG按目标尺寸和透明度铺到页面只关心缩放、定位、透明度和格式。调度线负责遍历目录、读取文件、分配任务、控制并发、写出结果和日志。三条线通过同一个配置结构解耦文本线不关心文件从哪来调度线也不关心水印长什么样。这样拆最大的好处是某条线出问题时不会殃及其他两条。比如后来图片线改alpha预处理逻辑文本线完全不用动调度线增加对加密文件的跳过策略也不会碰渲染逻辑。再往后如果需求扩展成加二维码水印只需要新开一条“条码线”而不是在现有代码里到处补丁。3. 核心实操从参数到批量执行一次跑通3.1 文本水印的关键参数与平铺写法文本水印我建议做成一套默认参数加用户覆盖的结构。默认参数来自大量真实文件观感测试字号36pt旋转45度颜色浅灰间距按水印本身高度的2到3倍来取。旋转45度是因为水平水印容易被正文遮挡视觉重点垂直又太僵硬斜向是最常见的防遮挡方向。平铺坐标是另一个重点。A4页面宽度约为595点一个36pt的文字横向跨度约150到200点纵向高度约40点。如果水平间隔取字号6倍即216点左右、垂直间隔取字号3.5倍即126点左右一页大约能出现六到八行水印视觉上既不空旷也不会过度压字。我实际工具里用的是下面的函数import fitz def render_text_watermark(page, text, size36, rotate45, color(0.6, 0.6, 0.6)): width, height page.rect.width, page.rect.height step_x, step_y size * 6, size * 3.5 fontname china-s fontfile C:/Windows/Fonts/simhei.ttf for x in range(-int(width), int(width) step_x, step_x): for y in range(-int(height), int(height) step_y, step_y): page.insert_text( fitz.Point(x, y), text, fontnamefontname, fontfilefontfile, fontsizesize, rotaterotate, colorcolor )注意循环的起始坐标从负数开始。如果不这样做45度斜向水印会在页面左上角缺一块看起来很不完整。这个小细节我第一次跑的时候没注意到铺出来四个角有三个角是空的整个页面像被裁剪过一样后来才意识到是起始坐标问题。另一个经验是纯浅灰color(0.6, 0.6, 0.6)在绝大多数阅读器里都稳定。很多教程教用真正的alpha半透明参数但某些PDF渲染器对透明度支持不一致屏幕上看着正常打印出来直接变成实色块。为了避免交付事故863默认用浅灰色模拟半透明观感同时在配置里保留透明度选项方便特殊渲染环境的人自行调整。3.2 图片水印的尺寸、定位和透明度处理图片水印比文本水印多两个变量素材尺寸和透明度。原图可能是一张1600像素的Logo页面宽度才595点直接插进去会占半页。所以第一步是按目标宽度等比缩放。我设的目标宽度为页面宽度的10%到20%A4下大约60到120点既能清晰识别品牌信息又不会干扰正文阅读。定位模式分成两种。平铺模式用于背景装饰类似文本水印按间距循环角落模式用于品牌归属固定在右上角或左下角距页面边缘约24点。实现时把模式设计成配置里写tile或corner两个字符串调度线完全不用关心具体坐标计算。透明度方面最稳妥的做法是先在图片层面预处理alpha通道再交给PDF插入。我遇到过一次直接把半透明PNG丢给PDF库处理结果在部分阅读器里显示成完全不透明色块的案例。用Pillow先把alpha整体压到目标值就能保证所有阅读器表现一致from PIL import Image im Image.open(logo.png).convert(RGBA) alpha im.split()[3].point(lambda a: int(a * 0.35)) im.putalpha(alpha) im.save(logo_faded.png)插入时用page.insert_image配合一个矩形区域等比缩放交给keep_proportion参数控制不需要自己算宽高比。PNG素材自带透明通道时insert_image会保留JPG没有alpha要做整体透明度只能走预处理路径。还有一个容易踩的坑如果输入图片是CMYK模式的JPG插入后颜色会明显偏色。所以我会在工具里把所有素材统一转成RGB或RGBA再走预处理逻辑避免出现“水印颜色和原图完全不一样”的诡异问题。3.3 目录扫描、并行输出与执行策略批量执行部分863的目录结构是输入目录、输出目录、配置文件三个要素。配置文件用JSONPython标准库直接读取部署时不引入额外依赖。一个典型的配置长这样{ input_dir: ./input, output_dir: ./output, mode: text, text: 内部资料, fontsize: 36, rotate: 45, color: [0.6, 0.6, 0.6], workers: 4, suffix: _watermarked }扫描时用pathlib而不是字符串拼接尤其在Windows环境中文路径和文件名很容易在字符串处理上翻车。过滤规则只匹配后缀为.pdf的文件大小写不敏感。实际交付场景通常需要处理按项目分好的多级目录所以我默认开启递归遍历并把原目录结构复制到输出目录方便后续按项目找文件。并行策略上PDF处理属于CPU和内存密集任务但单文件内部又必须逐页顺序处理。所以最合理的并发粒度是“一个文件一个任务”用进程池并发处理多个文件而不是在单文件内部开多线程。Python多线程在GIL限制下对这类任务提升有限ProcessPoolExecutor更直接。我在四核机器上实测一百个平均三十页的PDF顺序跑大约二十五分钟四个进程并行大约七分钟提速非常明显。如果机器内存有限可以减少进程数避免多个大文件同时驻留内存导致交换。3.4 命令行调用与日志输出示例配置写好后调用方式设计成一条命令python pdf_watermark.py --config config.json运行日志会打到终端同时写一份到日志文件。日志要记录三件事每个文件的起始处理时间、成功完成信息、失败原因。失败原因尤其重要批量处理里一个坏文件不该中断整个批次所以调度线会捕获异常并继续处理下一个文件最后汇总失败列表。核心调度代码结构如下from concurrent.futures import ProcessPoolExecutor, as_completed from pathlib import Path def process_one(pdf_path: Path, out_path: Path, config: dict): # 内部完成打开、渲染、保存 return pdf_path.name, True def run_batch(config: dict): pdfs list(Path(config[input_dir]).rglob(*.pdf)) with ProcessPoolExecutor(max_workersconfig.get(workers, 4)) as pool: futures [ pool.submit(process_one, p, out_dir / p.name, config) for p in pdfs ] for fut in as_completed(futures): name, ok fut.result() print(f{OK if ok else FAIL} {name})实际运行时的日志大概是这样的[10:02:31] START 销售方案-2024-06.pdf [10:02:35] OK 销售方案-2024-06.pdf (24 pages, 1.2s/page) [10:02:35] START 合同-总部-0873.pdf [10:02:41] FAIL 合同-总部-0873.pdf (encrypted, skip)一个好用的批量工具不只是把所有文件都处理完就算成功而是要把“哪些成功、哪些失败、为什么失败”讲清楚。否则一百个文件里漏掉一个事后根本无从查起。我后来又加了一个汇总csv输出里面列出所有文件的处理状态、耗时和失败原因交付给业务方时直接看这个文件就行。4. 避坑记录实际跑批量时遇到的典型问题4.1 中文字体变方块这是第一次跑文本水印遇到的第一个问题水印文字全是方块正文却正常。原因很直接PDF内置标准字体只有西文字符中文字体必须从外部字体文件嵌入。insert_text如果不指定fontfile默认走内置字体自然不认识中文。解决方式是注册中文字体并每次传入fontname和fontfile。Windows上可以用simhei.ttf或simsun.ttcLinux服务器上必须确保字体文件路径存在否则批量任务在服务器上跑会静默丢字或者直接报错。我把字体路径放进配置换机器时只改配置不碰代码。还有一个小坑不同字体的字符宽度不一样平铺步长最好按实际字宽微调否则文字可能互相重叠或间距过大。测试时先输出一页预览确认字形和疏密没问题再放开跑全量。4.2 加密、只读和损坏PDF的兜底生产环境里的PDF远比demo脏。我从测试同事手里拿到的第一批真实文件里有的是加密的有的设置过安全策略有的根本是坏文件。如果不做兜底批量任务会中途卡死或者进程直接崩溃。策略是打开时先判断加密状态。PyMuPDF可以用authenticate方法确认是否需要密码需要但没密码的就跳过并记录原因有密码且持有密码的先认证再继续。对于能打开但保存失败的文件靠保存时的异常捕获兜底。所有失败文件统一进入失败列表不让单个文件拖垮整个批次。我把常见的异常类型和对应行为整理成了一张表异常类型行为日志输出加密且无密码跳过encrypted, skip密码错误跳过auth failed文件损坏无法打开跳过not a valid pdf输出路径无权限记录失败permission denied字体缺失记录失败font missing这些兜底不复杂但少了它们工具只能在你自己的电脑上用换一台机器就露怯。4.3 大文件与内存问题单文件几十MB甚至上百MB并不罕见。如果一次性把所有页面处理完再保存内存会被占得很凶。我遇到的一个典型案例是八百多页的扫描版PDF原文件大约400MB处理到一半内存占用超过2GB机器开始卡到鼠标都飘。解决办法是调整处理节奏逐页渲染处理完直接保存不再额外持有输入和输出的完整拷贝。保存时设置deflateTrue和garbage3让PDF库清理无引用对象能明显压缩输出体积。多进程并行时进程数不要超过物理核心数太多否则多个大文件同时吃内存触发系统交换反而更慢。稳定之后我又把单文件处理改成先渲染临时文件再替换目标文件即使异常退出也不会破坏已经生成的输出。4.4 输出体积与清晰度的平衡图片水印如果按原始高分辨率插入但显示区域很小输出文件会塞进大量冗余图像数据体积明显膨胀。反过来如果素材本身分辨率太低显示区域放大后会糊成一片。图片水印目标宽度在60到120点之间时我通常把素材预缩放到目标宽度的2倍也就是120到240像素这个值是清晰度和体积的折中点。对于原PDF里已有的图像保存时不做过度压缩否则会损伤原文档清晰度。863的做法是只开启对象清理和字体压缩不碰原有图像流。实测下来只加文本水印的文件体积几乎不增加加图片水印的文件视Logo尺寸大小一般会增加几十到几百KB完全可以接受。如果对体积有严格限制可以在配置里增加一个新增水印图压缩等级选项但原有内容始终不动这是底线。工具跑完这段时间我自己最大的体会是加PDF水印这个需求难的不是画几个字、贴一张图而是把“参数可控、批量稳定、结果可追溯、失败可排查”这些工程细节都想到。文本水印的平铺起点、图片水印的alpha预处理、加密文件的跳过策略每一条单独看都不起眼但少了任何一条工具在生产环境里就撑不住。最后再分享一个小技巧正式跑全量之前先从输入目录里挑三个结构不完全一样的样本执行一遍人工打开输出文档看一眼确认水印密度、颜色、位置都符合预期再放开跑批量。这一步花不了两分钟能帮你避开“一百个文件全部处理完才发现Logo透明度错了”的大返工。