Python替换PDF文本的三种可靠方案：从原理到代码实战

1. 为什么用Python替换PDF文本总是踩坑

说实话，第一次接到“用Python查找并替换PDF中的文本”这个需求时，我觉得这还不简单？不就是读文件、找字符串、替换、保存一套组合拳吗。等真正打开一个PDF尝试改的时候才发现，这条路比想象中曲折得多。PDF根本不像Word那样有明确的段落和字符流，它更像是一张“拍好的照片”，文字只是按照精确坐标铺在页面上的图形指令。所以想替换其中的一段文字，本质上是在做一次“版面外科手术”。

当你尝试用正则表达式直接去改PDF源码，或者用某些库粗暴地替换文本对象，大概率会遇到两种情况：要么文件打不开，要么打开后原来的文字还在，新文字叠在一起，整个版面惨不忍睹。因为PDF内部有大量压缩流、字体编码映射、文本显示操作符，任何一个环节处理不好都会出问题。我后来在这类项目里摸爬滚打，总结出一套相对可靠的方案：先定位，再覆盖，最后重绘。这篇文章就把这些经验完整记录下来，重点讲清楚三种可行方案的原理、代码和坑，适合正在做合同批处理、PDF脱敏、报告模板更新的开发者参考。

1.1 PDF文本的存储方式决定了替换的难度

先简单还原一下PDF内部是什么样子。一个PDF文件由很多对象组成，页面内容存放在“内容流”里，流里面是一串操作指令。比如要显示“Hello”这个词，内容流里可能长这样：

BT /F1 12 Tf 72 720 Td (Hello) Tj ET

这里的Tj是“显示文本”操作符，前面的(Hello)是字符串，72 720 Td是坐标位置，/F1 12 Tf是字体和字号。在简单的文本文件里，找“(Hello)”替换成“(World)”似乎可行，但问题在于：内容流往往是被Flate算法压缩过的，而且文本字符串可能是十六进制形式，也可能被拆分到多个Tj/TJ操作符里。比如“Python”可能被拆成(Py)和(thon)，视觉上是连续的，但直接搜“Python”这个字符串根本搜不到。

更麻烦的是字体编码。PDF里的字符并不是直接存Unicode码点，而是查字体表之后再映射到字形。也就是说，内容流里的字节和最终显示的文字之间隔了一层。有些工具哪怕让你搜到了文字，也只是“识别”出来的结果，而不是真的可以编辑的原文。所以，替换PDF文本从来不是简单的“查找-替换”，而是“识别文本位置-删除旧区域-在相同位置绘制新文本”的复合操作。

1.2 实际项目里常见的替换需求

这类需求在自动化办公领域出现频率非常高，我接触到的大致有四种：

第一种是批量合同或报告模板替换。比如一家做合同归档的公司，每年需要把数千份旧合同里的甲方名称批量换成新主体，或者更新报告封面上的日期、编号。这种场景要求替换后视觉上尽量无痕，字体、字号、位置都不能差太多。

第二种是敏感信息脱敏。把PDF里的身份证号、手机号、姓名找到后盖住或者替换成“***”。这种场景其实不需要“还原美观”，反而更看重覆盖的彻底性，宁可留白也不能让敏感信息露出来。

第三种是表单类PDF的数据回填。有些PDF是基于AcroForm做的，里面已经有文本框字段，那其实应该走表单填充路线，而不是去改内容流。

第四种是扫描版PDF的处理。这类PDF本质是图片，里面根本没有文字层，任何基于文本的查找都失效，必须走OCR加图像重绘的路子。

不同场景对方案的选择影响很大，后面我展开讲的时候会逐个对应。

1.3 必须先建立的两个心态

我从这个项目里学到的第一课是：永远不要相信某个库能百分之百无损替换PDF文本。哪怕是最好的方案，也只适用于“文本层存在且结构相对简单”的PDF。所以动手之前，先判断这个PDF是不是“有救”的：用提取工具试试能不能正常抽出文字，能抽出来，才有替换的基础。

第二课是：替换的本质是“版面重绘”，不是“字符改写”。脑子里想清楚这五个步骤——打开文档、定位目标、删除目标区域、写入新文本、检查结果——后面所有代码都是围绕这个流程展开的。这样设计的好处是，即使遇到特殊情况，也能把问题精确定位到某一个环节，而不是眉毛胡子一把抓。

2. 常用PDF替换库怎么选：PyMuPDF、pikepdf与OCR方案

选型决定了项目的下限。很多新手一上来就选了一个只能提取文本的库，做到一半发现没法改写，只能推倒重来。我在选型之前通常会先问自己三个问题：PDF是文字版还是扫描版？需要处理中文还是只有英文？替换之后是追求“完全无痕”还是“内容正确即可”。这些问题答案不同，适用库也完全不同。

2.1 选型前先搞清三个问题

第一个问题，PDF来源是否可控。如果PDF是自己程序生成的，比如先做了一个报告模板再导出PDF，那最优雅的方案其实是在生成阶段就留好占位符，或者用表单字段填充，根本不需要事后查找替换。但大多数需求面对的是“别人给过来的PDF”，来源不可控，这时才需要事后替换。

第二个问题，要不要处理中文。中文字体体积大、嵌入方式复杂，很多PDF为了减小体积只嵌入了字形子集，或者干脆不嵌入字体靠阅读器本地字体渲染。这会导致替换中文时找不到可用字体，出现空白或方块。这个问题如果提前没想清楚，做到一半会非常头疼。

第三个问题，是写一次性脚本还是长期使用的工具。如果只是处理一两份文件，那简单粗暴的方案都可以；如果要批量跑几千个文件，就必须考虑性能、日志、失败恢复，甚至要有并行处理的设计。

2.2 主流库的优缺点对比

我实际用过不少库，下面把适合文本替换的几个列出来对比一下：

2.3 我推荐的选型结论

如果目标是“替换PDF中的文字并保持原版面”，我大部分时候直接选PyMuPDF，因为它的search_for可以准确找到一段文字在页面上的矩形位置，然后配合add_redact_annot和apply_redactions完成删除旧内容、绘制新内容的闭环。这个流程正好对应前面说的“版面重绘”思路，而且它对中文内置了CJK字体支持，省去不少麻烦。

如果PDF不是简单的单段文字，而是需要精确修改内容流，比如要把某个操作符或某个字体对象批量替换掉，那pikepdf更合适。它把压缩处理透明化了，读取流时自动解压，写入流时用make_stream包一层，不需要自己处理Flate编码。

对于扫描版PDF，没什么好纠结的，老老实实走OCR路线：把每一页转成图片，用OCR识别出目标文本的位置，然后用PIL在图片上涂掉旧文字、绘制新文字，最后把所有图片重新打包成一个PDF。这条路精度上限受制于OCR模型，但确实是扫描件的唯一可行解。

3. 三种可靠实操方案与完整代码

这一节是全文的核心，我把三种方案分别展开，代码可以直接抄走改改就用。每个方案我都会解释关键步骤为什么这么做，以及哪些地方容易踩雷。

3.1 方案一：PyMuPDF的“定位-覆盖-重绘”流程

这个方案适合绝大多数文字版PDF。先用page.search_for(old_text)找出所有目标文本的位置，返回的是矩形坐标列表；然后在每个矩形上添加一个redaction注解，指定要写入的新文本；最后调用page.apply_redactions()统一执行删除和重绘。这套机制的好处是，MuPDF会自己处理页面中与该区域相关的文字对象和图形对象，比手动去内容流里挖字符串安全得多。

下面是一个可以直接跑的函数：

import fitz def replace_text_in_pdf(input_path, output_path, old_text, new_text, fontname="china-s"): doc = fitz.open(input_path) replaced_count = 0 for page in doc: rects = page.search_for(old_text) if not rects: continue for rect in rects: # 字体大小根据原始矩形高度估算，适当缩小防止溢出 fontsize = max(4, rect.height - 1) page.add_redact_annot(rect, text=new_text, fontname=fontname, fontsize=fontsize) replaced_count += 1 # 每页收集完所有注解后，一次性执行删除和重绘 page.apply_redactions() # garbage=4 清理无用对象，deflate=True 压缩内容流 doc.save(output_path, garbage=4, deflate=True) print(f"替换完成，共处理 {replaced_count} 处") return replaced_count

使用方式很简单：

replace_text_in_pdf("old_report.pdf", "new_report.pdf", "旧公司名", "新公司名")

这里有几个细节值得展开讲。第一，search_for默认是大小写不敏感的，如果只想精确替换全词，我建议先看它的参数，比如hit_max可以限制命中次数，或者用page.search_for(old_text, quads=True)拿四边形来应对旋转文本。第二，fontname="china-s"是PyMuPDF内置的中文字体，它会在保存时嵌入到PDF里，不需要你额外提供字体文件。如果你要替换的文字是英文，不传这个参数问题也不大；但涉及中文时，强烈建议指定它，否则很容易出现替换后文字消失或变成方块的情况。第三，rect.height - 1这个估算是经验值，目的就是让新文本的字体高度不要超出原来区域太高。如果效果不理想，也可以固定写死一个字号，多试几次找到视觉上最协调的。

再补充一个批量场景里的常见需求：替换整篇文档所有页的某个词，同时还想记录每个文件替换了多少处。上面的函数已经统计了replaced_count，我一般会在外层包一层循环，把每个输入文件的路径和替换数量写进日志，方便后续核对。

3.2 方案二：pikepdf深入内容流做对象级替换

PyMuPDF虽然方便，但它不一定能处理所有场景。比如目标文本被拆分成了多个内容流，或者PDF生成工具对文件做了特殊优化，search_for可能搜不到完整词。这时可以绕过“搜索”这层，直接用pikepdf打开内容流，在流层面做替换。

先看一个最简示例：

import pikepdf with pikepdf.open("input.pdf") as pdf: for page in pdf.pages: contents = page.obj.get("/Contents") if contents is None: continue if isinstance(contents, list): data = b"".join([c.read_bytes() for c in contents]) else: data = contents.read_bytes() # read_bytes 返回的是解压后的内容流，用 latin-1 保持字节可逆映射 text = data.decode("latin-1") text = text.replace("(OldName)", "(NewName)") # 重新写回内容流，pikepdf会自动保留压缩方式 page.obj["/Contents"] = pdf.make_stream(text.encode("latin-1")) pdf.save("output.pdf", garbage=4)

为什么这里用latin-1解码而不是utf-8？因为内容流里除了文本字符串，还有大量操作符和数字，直接按UTF-8解码很可能报错。latin-1的特点是每个字节映射到相同码位的Unicode字符，解码永远不会失败，替换后再编码回去也不会改变非目标字节。代价是：如果你用正则表达式去匹配中文，在latin-1视角下看到的会是乱码一样的字节串，直接替换基本没法用。所以这个方案更适用于纯英文场景，或者你提前知道目标文本在流里就是以某种ASCII形式存在的。

还有一个值得注意的问题：内容流里的文本不一定都长成(OldName) Tj这样。有时候PDF会用十六进制字符串表示文本，比如<4F 6C 64 4E 61 6D 65> Tj；有时候会用TJ数组把多个字符串拼在一起，比如[(Ol)(dName)] TJ。遇到这些情况，简单替换就会失效。我的习惯是，先用pikepdf把第一页内容流打印出来瞄一眼，看看文本到底以什么形态存在，再决定正则怎么写。比如做一次“空字符归一化”的匹配：先把(Old)(Name)这种拆分的括号串合并成逻辑上的文本，再替换。这一步确实麻烦，但能做到内容流级别精确修改的方案本来就不多，pikepdf已经是最可控的了。

3.3 方案三：扫描版PDF走OCR识别与图像重绘

扫描版PDF没有文本层，完全是一张张图片。对这种文件，唯一可行的路径是：把每一页转成高分辨率图片，用OCR识别目标词的位置，然后在图片上覆盖旧文字并绘制新文字，最后重新导出为PDF。

流程示意代码如下：

from pdf2image import convert_from_path import pytesseract from PIL import Image, ImageDraw, ImageFont images = convert_from_path("scan.pdf", dpi=300) font = ImageFont.truetype("path/to/NotoSansCJK-Regular.ttc", 24) for idx, img in enumerate(images): data = pytesseract.image_to_data( img, lang="chi_sim+eng", output_type=pytesseract.Output.DICT, ) draw = ImageDraw.Draw(img) for i in range(len(data["text"])): if data["text"][i].strip() == "旧文本": x, y = data["left"][i], data["top"][i] w, h = data["width"][i], data["height"][i] # 用白色覆盖原区域，再绘制新文本 draw.rectangle([x, y, x + w, y + h], fill="white") draw.text((x, y), "新文本", font=font, fill="black") # 可以保存为图片，也可以最后统一转PDF img.save(f"page_{idx}.png")

这个方案的精度完全取决于OCR质量。实际操作中，我会先把图片做灰度化和二值化预处理，把背景噪点去掉，再交给tesseract，识别率会明显提升。300dpi是我试过认为性价比最高的分辨率，再高虽然识别效果好一点，但内存消耗和耗时都上去了，批量处理时压力很大。

另一个重要的避坑点是：OCR识别到的坐标是像素坐标，而最终输出PDF的页面尺寸以点为单位，两者换算关系取决于你最终怎么生成PDF。如果直接保存图片成PDF，图片尺寸就是页面尺寸，坐标自然对应；如果后续还要在PDF上加文本层，就得用pdf_scale之类的参数做换算。所以我个人建议，扫描版替换最稳的做法是“图片重绘后重新转PDF”，不要试图在半路给原PDF加层，容易把坐标搞混。

4. 替换PDF文本常见问题排查与避坑实录

方案能跑通只是第一步，真正折磨人的是各种莫名其妙的现象。这一节我把踩过的坑集中整理一下，每条都给出了现象、原因和可操作的解决办法，希望能帮你少走弯路。

4.1 明明有这个词，search_for就是找不到

这是最常遇到的问题。你肉眼明明看到页面上写着“Python”，但search_for就是返回空列表。原因通常有三种：文本被拆分成多个片段，字与字之间存在不可见的间距，或者文本以曲线/图片形式存在而不是真正的文本对象。

排查时可以先用page.get_text("words")把整页的词打出来，看看目标词是怎么被切分的。比如“Python”可能被识别成“Py”和“thon”两个词。对策是做一个空白字符归一化：把目标文本里的空格去掉，再把提取文本里的空格去掉，然后做包含匹配。还有一种更实用的做法，是搜目标词的一个连续子串，比如搜“thon”，命中后再检查前后是不是“Py”，拼起来确认是否完整匹配。这个思路在合同替换场景里特别管用，因为公司名经常被PDF排版拆得分崩离析。

4.2 替换中文后显示成空白或方块

替换英文基本没什么大问题，一到中文就露馅。核心原因是原PDF里的字体可能只嵌入了英文字形子集，或者压根没有嵌入中文字体，而PyMuPDF在redact时如果没有合适的字体可用，就会放弃绘制。对策很明确：在add_redact_annot里指定fontname="china-s"，这是MuPDF内置的简体中文CJK字体，保存时会自动嵌入。如果内置字体风格不满足需求，也可以传入外部字体文件：

page.add_redact_annot(rect, fontname="F0", fontfile="/path/to/simhei.ttf")

用外部字体的好处是风格可控，坏处是文件路径要存在，且字体文件可能很大。我一般先试内置的china-s，视觉效果能接受就不折腾了。

4.3 覆盖区域有残影或者旧文本没擦干净

apply_redactions()默认会删除区域内的文本，但不会删除该区域的图片和图形。如果你的原文本带下划线、底色或者水印，替换后这些图形元素可能还留在那里，看着就像“残影”。这时候需要给apply_redactions传参数：

page.apply_redactions( images=fitz.PDF_REDACT_IMAGE_REMOVE, graphics=fitz.PDF_REDACT_LINE_ART_REMOVE, )

但要注意，这样会把该区域内的所有图片和线条也一并删掉。所以要不要删图形，取决于具体场景。如果是脱敏需求，删得越干净越好；如果是替换合同正文，误删了下划线反而不美观。我的习惯是：先只删文本，保存看看效果，实在不行再扩大删除范围。

4.4 加密PDF提示权限不足

遇到加密PDF，fitz会直接报“cannot open encrypted document”，pikepdf会报密码错误。处理方式是在打开时传入密码：

doc = fitz.open("input.pdf", password="your_password")

或者：

pdf = pikepdf.open("input.pdf", password="your_password")

如果只是文档设置了打开密码而你恰好有密码，那问题不大；如果文档设置了编辑权限但允许打开，那读取本身没问题，保存时可能受限。这类情况我会用pikepdf重新保存一份，必要时在保存时指定是否加密。这里不做任何避开权限的讨论，只提醒一点：处理他人文档前，先确认有没有合法授权。

4.5 替换保存后文件尺寸异常增大

小文件替换一次变成几十MB，十有八九是保存参数没设对。PyMuPDF保存时要用garbage=4, deflate=True，前者清理无用对象，后者压缩流。pikepdf保存时对应的是garbage=4, compress_streams=True。如果用了这些参数文件还是很大，就检查一下是不是每页都通过了多个版本的redact注解，有些旧版注解会在apply后被保留下无用副本，这时可以试试先doc.tobytes(garbage=4, deflate=True)再写入新文件，效果通常更明显。

5. 项目落地经验与扩展思路

写到这儿，方案和坑都讲得差不多了，最后聊一下把这类代码落地成真正可用项目时我的经验。这些不是官方文档里的东西，纯粹是项目踩出来的。

5.1 动手前先给PDF做一次“体检”

我每次拿到一批PDF，第一件事不是写替换代码，而是先写一个检查脚本：打印文件页数、是否加密、每页能否提取文本、用了哪些字体。这一步能帮你快速判断这条文件走哪条路线。比如一个扫描PDF，再好的替换代码也没用，早发现早换方案。

一个很轻量的体检代码：

import fitz doc = fitz.open("input.pdf") print("页数:", doc.page_count) print("需要密码:", doc.needs_pass) for i, page in enumerate(doc): text = page.get_text().strip() fonts = page.get_fonts() print(f"第{i+1}页 文本长度:{len(text)} 字体数量:{len(fonts)}")

这段代码跑一遍，文件是不是有文字层、中文字体是不是正常嵌入，心里基本就有数了。

5.2 批量处理时的纪律性

处理大量文件时，我给自己立了几条规矩。第一条，绝不动原始文件，所有输出都写到新路径。第二条，先拿一个典型文件跑通，人工检查效果，再上全量。第三条，每个文件的替换数量、报错信息都写进日志，方便出问题时定位。第四条，替换完成后，再用提取文本的逻辑验证一遍：旧词不再出现，新词确实存在。这套流程看起来笨，但能拦住绝大多数低级事故。

如果文件数量大，可以考虑多进程并行，但我建议用多进程而不是多线程。原因是MuPDF内部很多操作不是线程安全的，多线程并行容易出现莫名其妙的问题，多进程各干各的反而稳。

5.3 后续可以扩展的方向

这个项目我后来扩展成了一个小工具，支持命令行调用、替换映射表、批量处理三个能力。如果再往下做，还有四个方向值得探索：第一，做成一个带简单界面的工具，让不懂代码的同事也能操作；第二，把“脱敏”能力做专，比如自动识别身份证号、手机号、邮箱，然后一键遮盖；第三，接入模板生成流程，在PDF生成阶段就留好变量占位，之后只需要替换占位符，比事后改版稳定太多；第四，针对频繁出现的排版问题，沉淀一份“字体映射表”，让替换更智能。

我自己在这种批量替换项目里最大的体会是：替换PDF文本不是字符串游戏，而是一次版面上的外科手术。与其到处找能“改源码”的魔法库，不如把识别、定位、删除、重绘这套流程想清楚。如果你手头正被某个PDF替换问题卡住，先别急着加特效，按体检、定位、覆盖、验证这个顺序走一遍，八成问题都能迎刃而解。最后留一个小技巧：每次保存前尽量先doc.close()前的最后一步再执行清理参数，减少内存占用，处理超大PDF时体感差别还是很明显的。