批量给PDF加文字水印、页眉页脚,是合同归档、图纸交付和方案流转中很典型的自动化需求。这个脚本基于 Python 的 PyMuPDF 库,代码里导入名为 fitz,不把页面转成图片,而是在原 PDF 页面内容流上追加绘制指令,原有文本、图片、链接等对象不会被栅格化。脚本拆成单文件处理函数和目录批量函数两层,输入输出目录分离,单个文件失败不阻断整批处理。
一、页面坐标与页眉页脚定位
PDF 坐标原点在页面左下角,y 轴向上,单位是 point,1 point 等于 1/72 英寸。A4 纸宽度 595 point、高度 842 point。页眉不能直接写 y=30,否则会跑到页面底部附近。正确做法是用页面高度减去顶部边距,再结合文字高度计算。更稳妥的是每页读取 page.rect,动态取 width 和 height,避免 A4、A3、扫描件混排时位置错乱。
页眉安全区可以设为 x 从 50 到页面宽度减 50,y 从顶部向下 30 到 80;页脚区域则从页面高度减 80 到页面高度减 30。文字在矩形区域内排版,align=1 表示居中。insert_textbox 会返回剩余空间,剩余值小于 0 说明文字没放下,页眉页脚字号建议控制在 8 到 12 point,文本不超过 20 个汉字。水印字号在 A4 上可用 46 point,A3 可提高到 60 point。
二、文字水印的三个关键参数
字体、透明度、旋转角度决定水印效果。PDF 默认 Helvetica 不带中文字符,中文文本容易乱码或不显示,必须嵌入中文字体文件。font_path 作为参数传入,Windows 可用 C:/Windows/Fonts/simhei.ttf 或 msyh.ttc,跨平台可优先选择开源字体。fontname='cn' 是自定义名称,fontfile 指定对应字体文件。如果 .ttc 集合字体解析失败,换成 .ttf 再试。
页眉页脚通常要清晰可读,fill_opacity 设为 1.0;真正的水印透明度在 0.2 到 0.35 比较合适。透明度最终由阅读器渲染决定,重要文档先打样张确认。页眉页脚水平放置,水印可旋转 30 度或 45 度,insert_text 的 rotate 参数以逆时针为正。旋转后文字包围盒会变化,水印基准点需要从页面中心往左上偏移,原文通过几次实验微调偏移量。
三、环境准备
Python 3.8 以上即可。建议使用虚拟环境,避免与全局库冲突。安装核心库:
安装后导入的模块名是 fitz,不是 PyMuPDF。可用下面的命令验证:
- python -c 'import fitz; print(fitz.__doc__)'
复制代码
能输出版本信息即可。国内镜像源可能更新滞后,遇到接口差异时以官方文档为准。Linux 服务器缺少中文字体时,可安装 fonts-wqy-microhei 一类开源字体包,字体路径不要硬编码。
四、单文件处理函数
核心逻辑是遍历每一页,分别绘制页眉、页脚和水印。页脚用 format 替换 {page} 和 {total},其中 total 来自 doc.page_count。保存时用 garbage=4 深度清理冗余对象,deflate=True 重新压缩内容流,控制输出体积。
- import os
- import fitz
- def add_pdf_watermark(input_path, output_path,
- header_text=None, footer_text=None, watermark_text=None,
- font_path=None,
- header_footer_fontsize=10,
- watermark_fontsize=46,
- header_footer_color=(0.1, 0.1, 0.1),
- watermark_color=(0.6, 0.0, 0.0),
- watermark_opacity=0.25):
- doc = fitz.open(input_path)
- total = doc.page_count
- for page_index in range(total):
- page = doc[page_index]
- rect = page.rect
- if header_text:
- header_rect = fitz.Rect(50, 30, rect.width - 50, 80)
- page.insert_textbox(
- header_rect,
- header_text,
- fontsize=header_footer_fontsize,
- fontname='cn',
- fontfile=font_path,
- align=1,
- color=header_footer_color,
- fill_opacity=1.0
- )
- if footer_text:
- footer_rect = fitz.Rect(50, rect.height - 80, rect.width - 50, rect.height - 30)
- footer_content = footer_text.format(page=page_index + 1, total=total)
- page.insert_textbox(
- footer_rect,
- footer_content,
- fontsize=header_footer_fontsize,
- fontname='cn',
- fontfile=font_path,
- align=1,
- color=header_footer_color,
- fill_opacity=1.0
- )
- if watermark_text:
- center_x = rect.width / 2
- center_y = rect.height / 2
- page.insert_text(
- (center_x - watermark_fontsize * 1.2, center_y),
- watermark_text,
- fontsize=watermark_fontsize,
- fontname='cn',
- fontfile=font_path,
- color=watermark_color,
- fill_opacity=watermark_opacity,
- rotate=30
- )
- doc.save(output_path, garbage=4, deflate=True)
- doc.close()
复制代码
这里 insert_textbox 用于页眉页脚,适合在矩形区域内控制居中、右对齐和边界;insert_text 用于水印,把文字当作整体放在指定坐标。水印坐标左侧偏移量与字体、字号有关,不需要精确到像素,但要避免旋转后遮挡正文。
五、目录批量处理
批量函数默认只处理输入目录第一层 PDF,不递归子目录,避免误处理其他文件。输出文件名保持不变,处理失败只打印 FAIL,不中断整批。V1.0 默认覆盖同名输出文件。
- def batch_add_watermark(input_dir, output_dir, **kwargs):
- os.makedirs(output_dir, exist_ok=True)
- for filename in os.listdir(input_dir):
- if not filename.lower().endswith('.pdf'):
- continue
- input_path = os.path.join(input_dir, filename)
- output_path = os.path.join(output_dir, filename)
- try:
- add_pdf_watermark(input_path, output_path, **kwargs)
- print('[OK]', filename)
- except Exception as e:
- print('[FAIL]', filename, '=>', e)
- batch_add_watermark(
- input_dir='D:/待处理文件',
- output_dir='D:/处理完成',
- header_text='内部资料 请勿外传',
- footer_text='第 {page} 页 / 共 {total} 页',
- watermark_text='机密',
- font_path='C:/Windows/Fonts/simhei.ttf',
- header_footer_fontsize=10,
- watermark_fontsize=46,
- watermark_opacity=0.3
- )
复制代码
批量处理时要把打开、处理、保存、关闭放在循环内部,add_pdf_watermark 在 doc.close() 后才返回,内存占用才稳定。输出目录不要放在输入目录内部,否则遍历时可能把刚生成的 PDF 当成新输入再次处理,造成重复叠加或无限循环。garbage=4 和 deflate=True 能明显减小输出体积,但过于激进的清理偶尔会带来阅读器兼容性问题,内部归档可使用,交付外部客户时可保留一份未压缩版本。
六、常见问题排查
中文水印乱码或消失,优先检查 font_path 是否存在、字体格式是否可解析,再确认 fontname 和 fontfile 是否配套。原文遇到 msyh.ttc 下中文变空白,换成 simhei.ttf 后正常,因此第一步是换字体文件,而不是先怀疑绘制逻辑。
页眉页脚位置对不上,要检查页面 rotation 属性。有些打印机驱动会把横向页面存成带旋转的纵向页面,page.rect 的宽高与绘制坐标空间可能不一致。可先遍历页面打印每页 rect 和 rotation 观察规律,必要时手动转换坐标,或用 page.set_rotation(0) 统一摆正,但这会改变原始页面呈现方式。
加密 PDF 直接 fitz.open() 可能抛异常。处理前判断 doc.is_encrypted,再用 authenticate 传入密码,失败则跳过。部分 PDF 只设置禁止编辑的权限密码,authenticate 后可以绘制内容,但保存时是否保留原权限标记取决于库版本,有严格安全要求时要单独设计保存策略。
七、V1.0 的边界与扩展方向
V1.0 已支持批量文字水印、顶部页眉、底部页脚、中文字体、自定义字号颜色透明度、输出目录自动创建和单文件异常捕获。限制是不支持图片水印、不递归子目录、不支持一页多个水印副本,也没有图形界面。后续可把参数改为 JSON 或 YAML 配置文件驱动,加入页眉 Logo、图片水印,以及按页码范围筛选,例如跳过封面、目录和签字页。单文件处理函数按“每页执行相同操作”设计,后续在循环中加入页码判断即可扩展页面范围控制。 |