PyPDF2无法直接添加水印，必须用PageObject.merge_page()将预生成的PDF格式水印页叠加到目标页上；水印PDF需匹配目标页尺寸、嵌入中文字体、设置透明度，且批量处理时须及时释放资源。
PyPDF2 无法直接添加水印，必须用 PageObject.merge_page()
很多人以为 PyPDF2 有类似 add_watermark() 的接口，实际没有。它只提供底层页面操作能力：先读取水印 PDF（通常单页），再用 merge_page() 把水印页“叠”到目标页上。这个过程本质是 PDF 对象的图形状态合并，不是图像贴图——所以水印必须是 PDF 格式，不能是 PNG/JPG。
常见错误现象：AttributeError: 'PageObject' object has no attribute 'add_watermark' 或水印位置错乱、文字模糊、透明度丢失。
- 水印 PDF 必须用支持透明度的工具生成（如 ReportLab、Inkscape 导出为 PDF/A，或用
pdfkit+ HTML/CSS） - 务必用
get_contents()和get_resources()检查水印页是否含真实内容（空页会静默失败） - 合并前建议调用
page.scale_by(1)统一缩放基准，避免因原始 PDF 缩放导致水印尺寸异常
水印 PDF 必须适配目标页尺寸，否则偏移或裁剪
PDF 页面有 mediabox（物理显示区域）、cropbox（实际内容裁剪区）。如果水印 PDF 的 mediabox 尺寸 ≠ 目标页尺寸，merge_page() 会按左下角原点对齐，导致水印出现在角落、被裁掉，或铺满整个页面。
使用场景：A4（595×842）文档加水印，但水印 PDF 是 Letter（612×792）或自定义 300×100 像素小图——都会出问题。
立即学习“Python免费学习笔记（深入）”；
- 生成水印时强制设为 A4 尺寸：
canvas = Canvas("watermark.pdf", pagesize=(595, 842)) - 或运行时动态缩放水印页：
watermark_page.scale_to(target_width, target_height)（需先获取目标页mediabox） - 更稳妥做法：用
watermark_page.merge_transformed_page(target_page, transform_matrix)手动控制位移和缩放（矩阵计算较复杂，一般用scale_by+rotate组合）
批量处理上百份 PDF 时，内存和文件句柄容易爆掉
PyPDF2 默认不释放中间对象，每处理一个 PDF 都会累积 PdfReader 和 PdfWriter 实例。处理 100+ 个 5MB 文件，内存可能飙升到 2GB+，还会触发 OSError: [Errno 24] Too many open files。
性能影响：未及时 close() 导致写入失败、部分文件为空、进程卡死在 writer.write()。
- 每个文件处理完立刻调用
reader.stream.close()和writer.close() - 用
with open(...)包裹输出文件写入，避免句柄泄漏 - 不要把所有
PdfReader存在列表里；逐个读、改、写、释放 - 示例关键片段：
for pdf_path in pdf_list: reader = PdfReader(pdf_path) writer = PdfWriter() for page in reader.pages: page.merge_page(watermark_page) writer.add_page(page) with open(f"output/{pdf_path.name}", "wb") as f: writer.write(f) reader.stream.close() # 必须加 del reader, writer
中文水印文字显示为方框？字体嵌入没做对
ReportLab 默认不嵌入中文字体，生成的水印 PDF 在合并后显示为口口口。这不是 PyPDF2 的问题，而是水印源本身缺失字体描述符。
兼容性影响：Windows 上用系统字体临时渲染可能正常，Linux/macOS 服务器无 GUI 环境必然失败；PDF 查看器（如 Preview、Edge）也会跳过缺失字体回退。
- 必须显式注册并嵌入字体：
pdfmetrics.registerFont(TTFont('SimSun', 'simsun.ttc'))，然后canvas.setFont('SimSun', 24) - 确认 TTC/TTF 文件路径有效，且有读权限（Docker 容器内常因挂载遗漏报
IOError: file not found） - 用
pdfinfo watermark.pdf检查输出中是否有Fonts:行并列出嵌入字体名
水印逻辑看似简单，真正卡住人的永远是 PDF 规范细节：尺寸对齐、字体嵌入、资源引用、内存生命周期。跑通第一个文件不难，让一百个都稳定输出，得盯着每一页的 mediabox、每一个 stream.close()、每一个字体路径。
