1. 项目缘起为什么选择PymuPDF来操作PDF如果你经常和PDF文件打交道尤其是需要批量处理、自动化修改内容那你肯定对市面上那些“点击式”的PDF编辑器又爱又恨。爱的是它们直观恨的是它们笨重、无法集成到工作流中更别提处理成百上千个文件了。几年前我接手了一个项目需要从几千份扫描版合同PDF中批量替换掉所有旧的公司Logo图片并更新页脚的联系电话文字。手动操作那简直是天方夜谭。当时我尝试了各种库最终锁定了PymuPDF也就是大家常说的fitz它用起来的感觉就像是在用瑞士军刀处理PDF——精准、高效而且几乎无所不能。PymuPDF是一个轻量级但功能极其强大的Python库它基于MuPDF这个高性能的渲染引擎。与PyPDF2、pdfplumber等库相比它的核心优势在于不仅能完美地读取PDF内容文字、图片、矢量图形更能直接修改PDF的底层元素。这意味着你可以像外科手术一样定位到PDF的某个坐标点删除一个文字块插入一张新图片或者修改一个矩形框的填充色而不会破坏文档的其他结构和格式。这对于需要程序化、精细化修改PDF的场景来说是无可替代的。今天我就结合自己踩过的坑和积累的经验带你深入PymuPDF的修改世界实现文字和图片的自由操控。2. 环境搭建与核心概念理解PymuPDF的“手术刀”工欲善其事必先利其器。在开始动“手术”之前我们必须准备好环境并理解PymuPDF是如何看待一个PDF文档的。2.1 安装与导入安装非常简单一条pip命令即可。建议使用虚拟环境来管理依赖。pip install PyMuPDF在代码中我们通常以fitz别名导入这是为了向其底层引擎MuPDF致敬也避免了与某些系统模块重名。import fitz # 这就是PyMuPDF2.2 核心对象模型Document与PagePymuPDF将PDF文档抽象为几个核心对象理解它们的关系至关重要Document (fitz.Document): 代表整个PDF文件。你可以把它想象成一个笔记本。Page (fitz.Page): 代表笔记本中的一页。绝大部分的修改操作都发生在Page对象上。Rect (fitz.Rect): 代表页面上的一个矩形区域。它由左上角(x0, y0)和右下角(x1, y1)的坐标定义。这是定位的基石。PymuPDF的页面坐标系原点(0, 0)在左上角X轴向右增长Y轴向下增长这与许多图形库一致但和PDF内部坐标系不同PymuPDF帮我们做了转换。TextPage / TextWriter: 用于提取和分析文本TextPage以及向页面写入新文本TextWriter。Pixmap: 用于处理图像数据可以从页面提取图片也可以将图片插入页面。重要提示PymuPDF修改PDF的原理并非直接编辑原始的PDF指令流而是在其之上进行“增量更新”。当你插入新内容时库会将这些新内容作为新的PDF对象附加到文件末尾。因此多次修改可能会导致文件体积略微增大但原始内容的结构不会被破坏兼容性极好。3. 精准定位找到你要修改的文字和图片在修改之前你必须先知道要改哪里。PymuPDF提供了强大的文本和图片搜索定位功能。3.1 定位文字多种搜索策略假设我们要把文档中所有的“旧公司名”替换成“新公司名”。首先得找到它们。方法一使用search_for()进行简单文本搜索这是最直接的方法返回一个包含匹配区域的矩形列表fitz.Rect。doc fitz.open(input.pdf) page doc[0] # 获取第一页 # 搜索“合同”二字 text_instances page.search_for(合同) for rect in text_instances: print(f找到文字在位置: {rect}) # rect包含了这四个坐标x0, y0, x1, y1 # 你可以在这个rect区域上进行覆盖、高亮等操作方法二使用get_text(“dict”)进行精细化文本块分析当需要更复杂的文本逻辑如按段落、字体、颜色筛选时这个方法更强大。它返回一个字典结构详细列出了页面上的每一个文本块span、每一行line及其位置、字体信息。text_dict page.get_text(“dict”) for block in text_dict[“blocks”]: if block[“type”] 0: # 类型0表示文本块 for line in block[“lines”]: for span in line[“spans”]: if “旧公司名” in span[“text”]: print(f”文本: ‘{span[‘text’]}’ 字体: ‘{span[‘font’]}’ 大小: {span[‘size’]} 位置: {span[‘bbox’]}“) # span[‘bbox’] 就是一个fitz.Rect对象方法三使用正则表达式搜索结合search_for和Python的re模块可以实现更灵活的匹配。import re pattern r”\d{11}“ # 匹配11位数字比如手机号 text page.get_text() for match in re.finditer(pattern, text): # 注意get_text()返回的纯文本位置信息不精确如需精确坐标需用方法二 print(f”找到疑似手机号: {match.group()}“)踩坑心得page.search_for()虽然方便但对于复杂排版或文字被图形部分遮挡的情况可能找不到或定位不准。get_text(“dict”)提供了最丰富的信息是进行复杂文本处理和替换的推荐方式。另外PDF中的文字可能由多个独立的span组成例如一个单词的每个字母都是独立的这在处理西文时需要注意。3.2 定位图片遍历与识别定位图片的思路与文字不同我们通常需要先提取页面上的所有图片然后根据图片的特征尺寸、哈希、内容来判断哪一张是目标。# 获取页面上的所有图片列表 image_list page.get_images(fullTrue) print(f”本页共有 {len(image_list)} 张图片。“) for img_index, img_info in enumerate(image_list): xref img_info[0] # 图片在PDF中的交叉引用号 pix fitz.Pixmap(doc, xref) # 创建Pixmap对象 # 根据特征判断例如图片尺寸 if pix.width 200 and pix.height 100: # 假设目标Logo是200x100 print(f”找到目标图片xref: {xref}, 尺寸: {pix.width}x{pix.height}“) # 接下来可以获取它的位置这需要额外步骤见下文 pix None # 释放Pixmap内存关键问题如何获取图片在页面上的位置Rectget_images()返回的信息不包括位置。要获取位置需要一个更底层的对象Image。# 先获取页面的显示列表display list它包含了所有绘制指令 dl page.get_displaylist() # 遍历显示列表中的项目 for item in dl: # 检查项目是否为图片 if item[0] “image”: # 元组的第一个元素是类型 rect item[1] # 元组的第二个元素就是图片的位置Rect xref item[2] # 交叉引用号 if rect.width 200 and rect.height 100: print(f”图片位置确定: {rect}“) # 现在你有了rect和xref可以在此进行替换实操技巧对于Logo、印章等固定位置的图片更简单的方法是直接知道它的大致坐标。你可以用PDF阅读器的测量工具或者写一段代码用PymuPDF画出页面的所有图片边框来辅助定位。记住Rect的坐标是浮点数比较时建议使用范围而非绝对相等。4. 修改文字从简单覆盖到完美替换找到了目标文字接下来就是修改。这里有几个不同层次的方案。4.1 方案一使用白色矩形覆盖后重写简单粗暴这是最直观的方法但效果取决于背景。text_instances page.search_for(“旧电话12345678”) for rect in text_instances: # 1. 画一个白色矩形覆盖原文字 shape page.new_shape() # 创建绘图对象 shape.draw_rect(rect) # 在目标矩形区域画矩形 shape.finish(fillfitz.utils.get_color(“white”), colorfitz.utils.get_color(“white”)) # 填充白色边框白色 shape.commit() # 提交绘制 # 2. 在相同位置写入新文字 # 注意需要计算字体大小和对齐这里简单演示 point rect.tl (0, rect.height*0.8) # 文本插入点粗略调整 page.insert_text(point, “新电话87654321”, fontsize11, fontname“helv”)缺点如果背景不是纯白色如有底纹、图片覆盖会显得很突兀。且新文字的字体、大小需要手动匹配很难做到完全一致。4.2 方案二使用add_redact_annot与apply_redactions官方修订模式这是PymuPDF提供的“修订”功能更规范。# 第一步添加修订注释Redaction Annotations annot_list [] text_instances page.search_for(“机密内容”) for rect in text_instances: annot page.add_redact_annot(rect, text“【已脱敏】”, fill(1,1,1)) # 用白色填充并准备替换文本 annot_list.append(annot) # 第二步应用所有修订 if annot_list: page.apply_redactions() # 这一步才会真正删除旧内容并写入新文本优点处理更标准生成的PDF符合规范。缺点替换文本的样式字体、颜色是固定的可能和上下文不协调。4.3 方案三精确计算与模拟原样式替换推荐这是追求完美效果的做法。核心思路是利用get_text(“dict”)获取原文本的精确样式字体、大小、颜色然后在原位置先覆盖背景再用完全相同的样式写入新文本。def replace_text_with_style(page, old_text, new_text): 用相同样式替换文本 text_dict page.get_text(“dict”) shapes page.new_shape() for block in text_dict[“blocks”]: if block[“type”] 0: for line in block[“lines”]: for span in line[“spans”]: if old_text in span[“text”]: bbox fitz.Rect(span[“bbox”]) # 1. 用背景色覆盖这里假设背景是白色复杂背景需另算 shapes.draw_rect(bbox) shapes.finish(fill(1,1,1), color(1,1,1)) # 2. 计算新文本的起始点左对齐 # 注意span[‘origin’] 是文本基线的起点但插入点通常需要y轴偏移 start_point fitz.Point(span[“bbox”][0], span[“bbox”][3]) # 左下角点 # 3. 用原样式插入新文本 page.insert_text( start_point, new_text, fontsizespan[“size”], fontnamespan[“font”], colorspan[“color”] # 注意color是RGB元组 ) shapes.commit() # 使用 replace_text_with_style(page, “旧公司”, “新公司”)核心难点与技巧文本的垂直对齐Baseline是最棘手的地方。span[“bbox”]是文本的包围框而insert_text的插入点默认是文本基线的左下角。直接使用bbox的角点可能导致文字错位。一个实用的技巧是先用原文字和获取到的样式、位置试插入一次观察偏移量然后计算一个修正值。对于多行或复杂段落建议直接使用TextWriter对象进行更精细的排版控制。5. 修改图片替换、删除与新增图片的修改相对直接因为不涉及样式匹配。5.1 替换现有图片这是最常见的需求。前提是你已经找到了目标图片的xref和位置rect。def replace_image(page, target_rect, new_image_path): 用新图片替换指定矩形区域的旧内容 # 1. 首先在目标区域覆盖一个白色背景删除旧内容 shape page.new_shape() shape.draw_rect(target_rect) shape.finish(fill(1,1,1), color(1,1,1)) shape.commit() # 2. 将新图片插入到相同位置 # 打开新图片文件 img_doc fitz.open(new_image_path) # 支持PNG, JPG等格式 img_bytes img_doc.convert_to_pdf() # 将图片转换为单页PDF img_pdf fitz.open(“pdf”, img_bytes) img_page img_pdf[0] # 计算图片缩放以适应目标矩形 # 这里选择等比例缩放并居中放置你也可以选择拉伸填充 img_width img_page.rect.width img_height img_page.rect.height target_width target_rect.width target_height target_rect.height scale_x target_width / img_width scale_y target_height / img_height scale min(scale_x, scale_y) # 选择较小的缩放比以保证图片完整放入 new_width img_width * scale new_height img_height * scale # 计算居中位置 x_offset target_rect.x0 (target_width - new_width) / 2 y_offset target_rect.y0 (target_height - new_height) / 2 new_rect fitz.Rect(x_offset, y_offset, x_offset new_width, y_offset new_height) # 3. 将图片PDF页面作为Form XObject插入到目标页面 page.show_pdf_page(new_rect, img_pdf, 0) # 关键API img_pdf.close() img_doc.close() # 使用假设我们已经通过3.2节的方法找到了目标rect # target_rect fitz.Rect(50, 100, 150, 150) # 举例 # replace_image(page, target_rect, “new_logo.png”)关键API解析page.show_pdf_page(rect, src, pno)是插入图片或PDF页面的核心方法。它可以将另一个PDF文档src的指定页码pno的内容渲染到当前页面的指定矩形rect内。我们将图片先转为单页PDF再利用这个功能插入能保证最好的兼容性和质量。5.2 删除图片删除操作就是用一个背景色矩形覆盖掉图片所在的区域。def delete_image(page, target_rect, background_color(1,1,1)): 删除指定矩形区域的内容 shape page.new_shape() shape.draw_rect(target_rect) shape.finish(fillbackground_color, colorbackground_color) shape.commit()注意事项覆盖删除法依赖于你知道背景色。如果背景是复杂的渐变或图片这种方法会留下一个“补丁”。更彻底的方法是直接操作PDF的底层对象流XObject但这需要更深入的PDF知识且PymuPDF的公开API没有直接提供删除特定XObject的方法。对于绝大多数纯色背景的文档覆盖法已经足够。5.3 在任意位置新增图片新增图片比替换更简单因为不需要定位旧内容。def insert_image_at(page, image_path, insert_rect, keep_aspect_ratioTrue): 在页面指定矩形区域插入图片 img_doc fitz.open(image_path) img_bytes img_doc.convert_to_pdf() img_pdf fitz.open(“pdf”, img_bytes) img_page img_pdf[0] if keep_aspect_ratio: # 等比例缩放并居中 img_width img_page.rect.width img_height img_page.rect.height target_width insert_rect.width target_height insert_rect.height scale_x target_width / img_width scale_y target_height / img_height scale min(scale_x, scale_y) new_width img_width * scale new_height img_height * scale x_offset insert_rect.x0 (target_width - new_width) / 2 y_offset insert_rect.y0 (target_height - new_height) / 2 final_rect fitz.Rect(x_offset, y_offset, x_offset new_width, y_offset new_height) else: # 拉伸填充整个矩形 final_rect insert_rect page.show_pdf_page(final_rect, img_pdf, 0) img_pdf.close() img_doc.close() # 示例在页面(200, 300)的位置插入一个100x50的图标 insert_rect fitz.Rect(200, 300, 300, 350) insert_image_at(page, “signature.png”, insert_rect)6. 实战案例批量替换合同PDF中的Logo与联系方式让我们整合以上所有知识完成开篇提到的那个真实项目批量处理合同PDF。需求输入一个包含多份PDF合同的文件夹。任务找到每一页中固定位置比如右上角的旧Logo图片并替换为新Logo。找到页脚处的旧公司电话和地址替换为新的。假设旧Logo在所有文档中的位置大致相同例如位于第一页的Rect(450, 50, 550, 100)区域。联系方式文字在最后一页的底部内容包含“电话XXX-XXXXXXX”。import os import fitz import re def batch_update_pdfs(input_dir, output_dir, new_logo_path, new_contact_info): 批量更新PDF合同 :param input_dir: 输入PDF文件夹路径 :param output_dir: 输出PDF文件夹路径 :param new_logo_path: 新Logo图片路径 :param new_contact_info: 新的联系方式文本字典如 {“phone”: “新电话”, “address”: “新地址”} os.makedirs(output_dir, exist_okTrue) 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) print(f”正在处理: {filename}“) doc fitz.open(input_path) # 任务1: 替换第一页的Logo (假设位置固定) if len(doc) 0: first_page doc[0] # 假设旧Logo在固定区域直接覆盖并插入新Logo logo_rect fitz.Rect(450, 50, 550, 100) # 先尝试用白色矩形覆盖该区域删除旧内容 shape first_page.new_shape() shape.draw_rect(logo_rect) shape.finish(fill(1,1,1), color(1,1,1)) shape.commit() # 插入新Logo insert_image_at(first_page, new_logo_path, logo_rect) # 任务2: 替换最后一页的联系方式 last_page doc[-1] # 获取页面文本使用正则匹配旧的联系方式格式 full_text last_page.get_text() # 假设旧电话格式为 “电话010-12345678” phone_pattern r”电话\d{3,4}-\d{7,8}” # 假设旧地址格式包含“地址”开头 address_pattern r”地址[^\n]” # 创建一个绘图对象用于本页的覆盖操作 shape last_page.new_shape() # 查找并替换电话 for match in re.finditer(phone_pattern, full_text): # 获取匹配文本的大致区域注意get_text()的文本位置不精确这里用search_for精确定位 search_rects last_page.search_for(match.group()) for rect in search_rects: shape.draw_rect(rect) # 在覆盖的矩形上方稍高位置插入新文本模拟原布局 insert_point fitz.Point(rect.x0, rect.y0 - 2) # 微调Y坐标 last_page.insert_text(insert_point, f”电话{new_contact_info[‘phone’]}”, fontsize10, fontname“helv”) # 查找并替换地址 (方法类似略) # ... shape.finish(fill(1,1,1), color(1,1,1)) shape.commit() # 保存修改后的文档 doc.save(output_path, garbage3, deflateTrue) # 压缩和清理无用对象 doc.close() print(f”处理完成: {filename}“) # 配置参数 config { “input_dir”: “./contracts/old”, “output_dir”: “./contracts/new”, “new_logo_path”: “./assets/new_logo.png”, “new_contact_info”: { “phone”: “400-888-9999”, “address”: “北京市海淀区新技术开发区” } } batch_update_pdfs(**config)批量处理的核心要点位置假设此方案基于Logo位置固定的假设。如果Logo位置不固定需要在每份文档中先用get_images()或get_displaylist()进行搜索和识别。文本定位精度用正则匹配全文再search_for定位比单纯用search_for更可靠因为可以处理换行等情况。但对于格式极其复杂的页脚可能需要用到get_text(“dict”)来获取精确的文本块位置。性能与内存处理大量PDF时注意及时关闭文档对象(doc.close())并使用garbage和deflate参数优化输出文件大小。错误处理生产环境中务必添加try...except处理损坏的PDF文件或意外的页面结构。7. 进阶技巧与避坑指南掌握了基本操作后这些进阶技巧和常见坑点能让你事半功倍。7.1 处理中文字体与编码在插入中文文本时如果指定了不包含中文字符的字体如默认的helv会导致显示为空白或乱码。解决方案指定一个支持中文的字体文件。# 方法使用字体文件 font_path “/path/to/your/Songti.ttf” # 宋体字体文件路径 font_buffer open(font_path, “rb”).read() # 将字体添加到PDF资源中 page.insert_text(point, “中文内容”, fontsize12, fontname“scjs”, fontbufferfont_buffer)注意fontname可以任意取一个别名fontbuffer参数才是关键。添加的字体只会嵌入到当前文档中。7.2 处理扫描件PDF图片型PDF对于扫描生成的PDFget_text()可能返回空字符串因为页面内容是一张图片而非文本。解决方案先进行OCR识别但PymuPDF本身不包含OCR功能。你需要集成像pytesseract这样的OCR库。流程是用PymuPDF将页面渲染成高分辨率图片然后用OCR库识别文字和位置最后再根据OCR结果进行“覆盖重写”式的修改。这属于更复杂的混合处理流程。7.3 修改的保存与优化doc.save()方法有几个关键参数garbage3: 进行完整的垃圾回收删除文档中所有未引用的对象能显著减小文件大小。deflateTrue: 对PDF内部的流进行压缩。incrementalFalse: 默认即为False表示保存完整的新文件。如果为True则以增量方式保存会保留原始版本文件会变大。建议最终保存时使用doc.save(output_path, garbage3, deflateTrue)。7.4 常见错误排查AttributeError: ‘Document’ object has no attribute ‘search_for’: 你错误地在Document对象上调用方法了。search_for是Page对象的方法。插入的文本或图片不显示检查坐标是否在页面可视范围内page.rect。检查插入操作是否在save之前。确认用于覆盖的白色矩形是否完全盖住了旧内容。修改后文件异常大可能是因为重复插入了大量内容而没有进行垃圾回收。确保使用garbage参数。另外避免在循环中反复打开保存同一个文档。内存泄漏在处理大量图片时fitz.Pixmap对象要及时设置为None以释放内存。使用with语句管理文档对象是个好习惯。7.5 性能优化建议批量操作时复用资源例如如果需要向多个页面插入同一张图片不要每次都从文件加载并转换。可以提前将图片转换为PDFfitz.Document对象然后在每个页面插入时复用这个对象。减少不必要的渲染get_text(“dict”)和get_displaylist()是相对耗时的操作。如果页面结构简单或位置已知尽量避免全页遍历。使用多进程如果处理成千上万个独立PDF文件可以考虑使用Python的multiprocessing模块并行处理。PymuPDF就像给你的Python脚本装上了一把可以精细雕刻PDF的手术刀。从简单的文本替换到复杂的版式调整它都能提供底层而强大的支持。掌握它的核心在于理解PDF的页面坐标系、对象模型以及“覆盖-重绘”的修改哲学。开始可能会在坐标计算和字体处理上踩些坑但一旦跑通你会发现自动化处理PDF的世界是如此开阔。我至今还记得第一次用脚本成功批量更新完几千份合同后那种解放双手的畅快感。希望这篇详尽的指南能帮你把这份畅快感提前。
Python自动化PDF修改：PyMuPDF精准定位与替换文字图片实战
1. 项目缘起为什么选择PymuPDF来操作PDF如果你经常和PDF文件打交道尤其是需要批量处理、自动化修改内容那你肯定对市面上那些“点击式”的PDF编辑器又爱又恨。爱的是它们直观恨的是它们笨重、无法集成到工作流中更别提处理成百上千个文件了。几年前我接手了一个项目需要从几千份扫描版合同PDF中批量替换掉所有旧的公司Logo图片并更新页脚的联系电话文字。手动操作那简直是天方夜谭。当时我尝试了各种库最终锁定了PymuPDF也就是大家常说的fitz它用起来的感觉就像是在用瑞士军刀处理PDF——精准、高效而且几乎无所不能。PymuPDF是一个轻量级但功能极其强大的Python库它基于MuPDF这个高性能的渲染引擎。与PyPDF2、pdfplumber等库相比它的核心优势在于不仅能完美地读取PDF内容文字、图片、矢量图形更能直接修改PDF的底层元素。这意味着你可以像外科手术一样定位到PDF的某个坐标点删除一个文字块插入一张新图片或者修改一个矩形框的填充色而不会破坏文档的其他结构和格式。这对于需要程序化、精细化修改PDF的场景来说是无可替代的。今天我就结合自己踩过的坑和积累的经验带你深入PymuPDF的修改世界实现文字和图片的自由操控。2. 环境搭建与核心概念理解PymuPDF的“手术刀”工欲善其事必先利其器。在开始动“手术”之前我们必须准备好环境并理解PymuPDF是如何看待一个PDF文档的。2.1 安装与导入安装非常简单一条pip命令即可。建议使用虚拟环境来管理依赖。pip install PyMuPDF在代码中我们通常以fitz别名导入这是为了向其底层引擎MuPDF致敬也避免了与某些系统模块重名。import fitz # 这就是PyMuPDF2.2 核心对象模型Document与PagePymuPDF将PDF文档抽象为几个核心对象理解它们的关系至关重要Document (fitz.Document): 代表整个PDF文件。你可以把它想象成一个笔记本。Page (fitz.Page): 代表笔记本中的一页。绝大部分的修改操作都发生在Page对象上。Rect (fitz.Rect): 代表页面上的一个矩形区域。它由左上角(x0, y0)和右下角(x1, y1)的坐标定义。这是定位的基石。PymuPDF的页面坐标系原点(0, 0)在左上角X轴向右增长Y轴向下增长这与许多图形库一致但和PDF内部坐标系不同PymuPDF帮我们做了转换。TextPage / TextWriter: 用于提取和分析文本TextPage以及向页面写入新文本TextWriter。Pixmap: 用于处理图像数据可以从页面提取图片也可以将图片插入页面。重要提示PymuPDF修改PDF的原理并非直接编辑原始的PDF指令流而是在其之上进行“增量更新”。当你插入新内容时库会将这些新内容作为新的PDF对象附加到文件末尾。因此多次修改可能会导致文件体积略微增大但原始内容的结构不会被破坏兼容性极好。3. 精准定位找到你要修改的文字和图片在修改之前你必须先知道要改哪里。PymuPDF提供了强大的文本和图片搜索定位功能。3.1 定位文字多种搜索策略假设我们要把文档中所有的“旧公司名”替换成“新公司名”。首先得找到它们。方法一使用search_for()进行简单文本搜索这是最直接的方法返回一个包含匹配区域的矩形列表fitz.Rect。doc fitz.open(input.pdf) page doc[0] # 获取第一页 # 搜索“合同”二字 text_instances page.search_for(合同) for rect in text_instances: print(f找到文字在位置: {rect}) # rect包含了这四个坐标x0, y0, x1, y1 # 你可以在这个rect区域上进行覆盖、高亮等操作方法二使用get_text(“dict”)进行精细化文本块分析当需要更复杂的文本逻辑如按段落、字体、颜色筛选时这个方法更强大。它返回一个字典结构详细列出了页面上的每一个文本块span、每一行line及其位置、字体信息。text_dict page.get_text(“dict”) for block in text_dict[“blocks”]: if block[“type”] 0: # 类型0表示文本块 for line in block[“lines”]: for span in line[“spans”]: if “旧公司名” in span[“text”]: print(f”文本: ‘{span[‘text’]}’ 字体: ‘{span[‘font’]}’ 大小: {span[‘size’]} 位置: {span[‘bbox’]}“) # span[‘bbox’] 就是一个fitz.Rect对象方法三使用正则表达式搜索结合search_for和Python的re模块可以实现更灵活的匹配。import re pattern r”\d{11}“ # 匹配11位数字比如手机号 text page.get_text() for match in re.finditer(pattern, text): # 注意get_text()返回的纯文本位置信息不精确如需精确坐标需用方法二 print(f”找到疑似手机号: {match.group()}“)踩坑心得page.search_for()虽然方便但对于复杂排版或文字被图形部分遮挡的情况可能找不到或定位不准。get_text(“dict”)提供了最丰富的信息是进行复杂文本处理和替换的推荐方式。另外PDF中的文字可能由多个独立的span组成例如一个单词的每个字母都是独立的这在处理西文时需要注意。3.2 定位图片遍历与识别定位图片的思路与文字不同我们通常需要先提取页面上的所有图片然后根据图片的特征尺寸、哈希、内容来判断哪一张是目标。# 获取页面上的所有图片列表 image_list page.get_images(fullTrue) print(f”本页共有 {len(image_list)} 张图片。“) for img_index, img_info in enumerate(image_list): xref img_info[0] # 图片在PDF中的交叉引用号 pix fitz.Pixmap(doc, xref) # 创建Pixmap对象 # 根据特征判断例如图片尺寸 if pix.width 200 and pix.height 100: # 假设目标Logo是200x100 print(f”找到目标图片xref: {xref}, 尺寸: {pix.width}x{pix.height}“) # 接下来可以获取它的位置这需要额外步骤见下文 pix None # 释放Pixmap内存关键问题如何获取图片在页面上的位置Rectget_images()返回的信息不包括位置。要获取位置需要一个更底层的对象Image。# 先获取页面的显示列表display list它包含了所有绘制指令 dl page.get_displaylist() # 遍历显示列表中的项目 for item in dl: # 检查项目是否为图片 if item[0] “image”: # 元组的第一个元素是类型 rect item[1] # 元组的第二个元素就是图片的位置Rect xref item[2] # 交叉引用号 if rect.width 200 and rect.height 100: print(f”图片位置确定: {rect}“) # 现在你有了rect和xref可以在此进行替换实操技巧对于Logo、印章等固定位置的图片更简单的方法是直接知道它的大致坐标。你可以用PDF阅读器的测量工具或者写一段代码用PymuPDF画出页面的所有图片边框来辅助定位。记住Rect的坐标是浮点数比较时建议使用范围而非绝对相等。4. 修改文字从简单覆盖到完美替换找到了目标文字接下来就是修改。这里有几个不同层次的方案。4.1 方案一使用白色矩形覆盖后重写简单粗暴这是最直观的方法但效果取决于背景。text_instances page.search_for(“旧电话12345678”) for rect in text_instances: # 1. 画一个白色矩形覆盖原文字 shape page.new_shape() # 创建绘图对象 shape.draw_rect(rect) # 在目标矩形区域画矩形 shape.finish(fillfitz.utils.get_color(“white”), colorfitz.utils.get_color(“white”)) # 填充白色边框白色 shape.commit() # 提交绘制 # 2. 在相同位置写入新文字 # 注意需要计算字体大小和对齐这里简单演示 point rect.tl (0, rect.height*0.8) # 文本插入点粗略调整 page.insert_text(point, “新电话87654321”, fontsize11, fontname“helv”)缺点如果背景不是纯白色如有底纹、图片覆盖会显得很突兀。且新文字的字体、大小需要手动匹配很难做到完全一致。4.2 方案二使用add_redact_annot与apply_redactions官方修订模式这是PymuPDF提供的“修订”功能更规范。# 第一步添加修订注释Redaction Annotations annot_list [] text_instances page.search_for(“机密内容”) for rect in text_instances: annot page.add_redact_annot(rect, text“【已脱敏】”, fill(1,1,1)) # 用白色填充并准备替换文本 annot_list.append(annot) # 第二步应用所有修订 if annot_list: page.apply_redactions() # 这一步才会真正删除旧内容并写入新文本优点处理更标准生成的PDF符合规范。缺点替换文本的样式字体、颜色是固定的可能和上下文不协调。4.3 方案三精确计算与模拟原样式替换推荐这是追求完美效果的做法。核心思路是利用get_text(“dict”)获取原文本的精确样式字体、大小、颜色然后在原位置先覆盖背景再用完全相同的样式写入新文本。def replace_text_with_style(page, old_text, new_text): 用相同样式替换文本 text_dict page.get_text(“dict”) shapes page.new_shape() for block in text_dict[“blocks”]: if block[“type”] 0: for line in block[“lines”]: for span in line[“spans”]: if old_text in span[“text”]: bbox fitz.Rect(span[“bbox”]) # 1. 用背景色覆盖这里假设背景是白色复杂背景需另算 shapes.draw_rect(bbox) shapes.finish(fill(1,1,1), color(1,1,1)) # 2. 计算新文本的起始点左对齐 # 注意span[‘origin’] 是文本基线的起点但插入点通常需要y轴偏移 start_point fitz.Point(span[“bbox”][0], span[“bbox”][3]) # 左下角点 # 3. 用原样式插入新文本 page.insert_text( start_point, new_text, fontsizespan[“size”], fontnamespan[“font”], colorspan[“color”] # 注意color是RGB元组 ) shapes.commit() # 使用 replace_text_with_style(page, “旧公司”, “新公司”)核心难点与技巧文本的垂直对齐Baseline是最棘手的地方。span[“bbox”]是文本的包围框而insert_text的插入点默认是文本基线的左下角。直接使用bbox的角点可能导致文字错位。一个实用的技巧是先用原文字和获取到的样式、位置试插入一次观察偏移量然后计算一个修正值。对于多行或复杂段落建议直接使用TextWriter对象进行更精细的排版控制。5. 修改图片替换、删除与新增图片的修改相对直接因为不涉及样式匹配。5.1 替换现有图片这是最常见的需求。前提是你已经找到了目标图片的xref和位置rect。def replace_image(page, target_rect, new_image_path): 用新图片替换指定矩形区域的旧内容 # 1. 首先在目标区域覆盖一个白色背景删除旧内容 shape page.new_shape() shape.draw_rect(target_rect) shape.finish(fill(1,1,1), color(1,1,1)) shape.commit() # 2. 将新图片插入到相同位置 # 打开新图片文件 img_doc fitz.open(new_image_path) # 支持PNG, JPG等格式 img_bytes img_doc.convert_to_pdf() # 将图片转换为单页PDF img_pdf fitz.open(“pdf”, img_bytes) img_page img_pdf[0] # 计算图片缩放以适应目标矩形 # 这里选择等比例缩放并居中放置你也可以选择拉伸填充 img_width img_page.rect.width img_height img_page.rect.height target_width target_rect.width target_height target_rect.height scale_x target_width / img_width scale_y target_height / img_height scale min(scale_x, scale_y) # 选择较小的缩放比以保证图片完整放入 new_width img_width * scale new_height img_height * scale # 计算居中位置 x_offset target_rect.x0 (target_width - new_width) / 2 y_offset target_rect.y0 (target_height - new_height) / 2 new_rect fitz.Rect(x_offset, y_offset, x_offset new_width, y_offset new_height) # 3. 将图片PDF页面作为Form XObject插入到目标页面 page.show_pdf_page(new_rect, img_pdf, 0) # 关键API img_pdf.close() img_doc.close() # 使用假设我们已经通过3.2节的方法找到了目标rect # target_rect fitz.Rect(50, 100, 150, 150) # 举例 # replace_image(page, target_rect, “new_logo.png”)关键API解析page.show_pdf_page(rect, src, pno)是插入图片或PDF页面的核心方法。它可以将另一个PDF文档src的指定页码pno的内容渲染到当前页面的指定矩形rect内。我们将图片先转为单页PDF再利用这个功能插入能保证最好的兼容性和质量。5.2 删除图片删除操作就是用一个背景色矩形覆盖掉图片所在的区域。def delete_image(page, target_rect, background_color(1,1,1)): 删除指定矩形区域的内容 shape page.new_shape() shape.draw_rect(target_rect) shape.finish(fillbackground_color, colorbackground_color) shape.commit()注意事项覆盖删除法依赖于你知道背景色。如果背景是复杂的渐变或图片这种方法会留下一个“补丁”。更彻底的方法是直接操作PDF的底层对象流XObject但这需要更深入的PDF知识且PymuPDF的公开API没有直接提供删除特定XObject的方法。对于绝大多数纯色背景的文档覆盖法已经足够。5.3 在任意位置新增图片新增图片比替换更简单因为不需要定位旧内容。def insert_image_at(page, image_path, insert_rect, keep_aspect_ratioTrue): 在页面指定矩形区域插入图片 img_doc fitz.open(image_path) img_bytes img_doc.convert_to_pdf() img_pdf fitz.open(“pdf”, img_bytes) img_page img_pdf[0] if keep_aspect_ratio: # 等比例缩放并居中 img_width img_page.rect.width img_height img_page.rect.height target_width insert_rect.width target_height insert_rect.height scale_x target_width / img_width scale_y target_height / img_height scale min(scale_x, scale_y) new_width img_width * scale new_height img_height * scale x_offset insert_rect.x0 (target_width - new_width) / 2 y_offset insert_rect.y0 (target_height - new_height) / 2 final_rect fitz.Rect(x_offset, y_offset, x_offset new_width, y_offset new_height) else: # 拉伸填充整个矩形 final_rect insert_rect page.show_pdf_page(final_rect, img_pdf, 0) img_pdf.close() img_doc.close() # 示例在页面(200, 300)的位置插入一个100x50的图标 insert_rect fitz.Rect(200, 300, 300, 350) insert_image_at(page, “signature.png”, insert_rect)6. 实战案例批量替换合同PDF中的Logo与联系方式让我们整合以上所有知识完成开篇提到的那个真实项目批量处理合同PDF。需求输入一个包含多份PDF合同的文件夹。任务找到每一页中固定位置比如右上角的旧Logo图片并替换为新Logo。找到页脚处的旧公司电话和地址替换为新的。假设旧Logo在所有文档中的位置大致相同例如位于第一页的Rect(450, 50, 550, 100)区域。联系方式文字在最后一页的底部内容包含“电话XXX-XXXXXXX”。import os import fitz import re def batch_update_pdfs(input_dir, output_dir, new_logo_path, new_contact_info): 批量更新PDF合同 :param input_dir: 输入PDF文件夹路径 :param output_dir: 输出PDF文件夹路径 :param new_logo_path: 新Logo图片路径 :param new_contact_info: 新的联系方式文本字典如 {“phone”: “新电话”, “address”: “新地址”} os.makedirs(output_dir, exist_okTrue) 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) print(f”正在处理: {filename}“) doc fitz.open(input_path) # 任务1: 替换第一页的Logo (假设位置固定) if len(doc) 0: first_page doc[0] # 假设旧Logo在固定区域直接覆盖并插入新Logo logo_rect fitz.Rect(450, 50, 550, 100) # 先尝试用白色矩形覆盖该区域删除旧内容 shape first_page.new_shape() shape.draw_rect(logo_rect) shape.finish(fill(1,1,1), color(1,1,1)) shape.commit() # 插入新Logo insert_image_at(first_page, new_logo_path, logo_rect) # 任务2: 替换最后一页的联系方式 last_page doc[-1] # 获取页面文本使用正则匹配旧的联系方式格式 full_text last_page.get_text() # 假设旧电话格式为 “电话010-12345678” phone_pattern r”电话\d{3,4}-\d{7,8}” # 假设旧地址格式包含“地址”开头 address_pattern r”地址[^\n]” # 创建一个绘图对象用于本页的覆盖操作 shape last_page.new_shape() # 查找并替换电话 for match in re.finditer(phone_pattern, full_text): # 获取匹配文本的大致区域注意get_text()的文本位置不精确这里用search_for精确定位 search_rects last_page.search_for(match.group()) for rect in search_rects: shape.draw_rect(rect) # 在覆盖的矩形上方稍高位置插入新文本模拟原布局 insert_point fitz.Point(rect.x0, rect.y0 - 2) # 微调Y坐标 last_page.insert_text(insert_point, f”电话{new_contact_info[‘phone’]}”, fontsize10, fontname“helv”) # 查找并替换地址 (方法类似略) # ... shape.finish(fill(1,1,1), color(1,1,1)) shape.commit() # 保存修改后的文档 doc.save(output_path, garbage3, deflateTrue) # 压缩和清理无用对象 doc.close() print(f”处理完成: {filename}“) # 配置参数 config { “input_dir”: “./contracts/old”, “output_dir”: “./contracts/new”, “new_logo_path”: “./assets/new_logo.png”, “new_contact_info”: { “phone”: “400-888-9999”, “address”: “北京市海淀区新技术开发区” } } batch_update_pdfs(**config)批量处理的核心要点位置假设此方案基于Logo位置固定的假设。如果Logo位置不固定需要在每份文档中先用get_images()或get_displaylist()进行搜索和识别。文本定位精度用正则匹配全文再search_for定位比单纯用search_for更可靠因为可以处理换行等情况。但对于格式极其复杂的页脚可能需要用到get_text(“dict”)来获取精确的文本块位置。性能与内存处理大量PDF时注意及时关闭文档对象(doc.close())并使用garbage和deflate参数优化输出文件大小。错误处理生产环境中务必添加try...except处理损坏的PDF文件或意外的页面结构。7. 进阶技巧与避坑指南掌握了基本操作后这些进阶技巧和常见坑点能让你事半功倍。7.1 处理中文字体与编码在插入中文文本时如果指定了不包含中文字符的字体如默认的helv会导致显示为空白或乱码。解决方案指定一个支持中文的字体文件。# 方法使用字体文件 font_path “/path/to/your/Songti.ttf” # 宋体字体文件路径 font_buffer open(font_path, “rb”).read() # 将字体添加到PDF资源中 page.insert_text(point, “中文内容”, fontsize12, fontname“scjs”, fontbufferfont_buffer)注意fontname可以任意取一个别名fontbuffer参数才是关键。添加的字体只会嵌入到当前文档中。7.2 处理扫描件PDF图片型PDF对于扫描生成的PDFget_text()可能返回空字符串因为页面内容是一张图片而非文本。解决方案先进行OCR识别但PymuPDF本身不包含OCR功能。你需要集成像pytesseract这样的OCR库。流程是用PymuPDF将页面渲染成高分辨率图片然后用OCR库识别文字和位置最后再根据OCR结果进行“覆盖重写”式的修改。这属于更复杂的混合处理流程。7.3 修改的保存与优化doc.save()方法有几个关键参数garbage3: 进行完整的垃圾回收删除文档中所有未引用的对象能显著减小文件大小。deflateTrue: 对PDF内部的流进行压缩。incrementalFalse: 默认即为False表示保存完整的新文件。如果为True则以增量方式保存会保留原始版本文件会变大。建议最终保存时使用doc.save(output_path, garbage3, deflateTrue)。7.4 常见错误排查AttributeError: ‘Document’ object has no attribute ‘search_for’: 你错误地在Document对象上调用方法了。search_for是Page对象的方法。插入的文本或图片不显示检查坐标是否在页面可视范围内page.rect。检查插入操作是否在save之前。确认用于覆盖的白色矩形是否完全盖住了旧内容。修改后文件异常大可能是因为重复插入了大量内容而没有进行垃圾回收。确保使用garbage参数。另外避免在循环中反复打开保存同一个文档。内存泄漏在处理大量图片时fitz.Pixmap对象要及时设置为None以释放内存。使用with语句管理文档对象是个好习惯。7.5 性能优化建议批量操作时复用资源例如如果需要向多个页面插入同一张图片不要每次都从文件加载并转换。可以提前将图片转换为PDFfitz.Document对象然后在每个页面插入时复用这个对象。减少不必要的渲染get_text(“dict”)和get_displaylist()是相对耗时的操作。如果页面结构简单或位置已知尽量避免全页遍历。使用多进程如果处理成千上万个独立PDF文件可以考虑使用Python的multiprocessing模块并行处理。PymuPDF就像给你的Python脚本装上了一把可以精细雕刻PDF的手术刀。从简单的文本替换到复杂的版式调整它都能提供底层而强大的支持。掌握它的核心在于理解PDF的页面坐标系、对象模型以及“覆盖-重绘”的修改哲学。开始可能会在坐标计算和字体处理上踩些坑但一旦跑通你会发现自动化处理PDF的世界是如此开阔。我至今还记得第一次用脚本成功批量更新完几千份合同后那种解放双手的畅快感。希望这篇详尽的指南能帮你把这份畅快感提前。
