拓冰网站定制 
在实际办公和工程文档处理中PDF 的定位一直是“最终交付格式”而不是“可编辑格式”。要把合同里的错别字改掉、给扫描件加上可检索文字、把十几份 PDF 合成一个归档文件很多人第一反应是打开在线转换站。但上传大文件、隐私文件、批量素材时传输和调用次数又成为新的瓶颈。与其到处找收费 PDF 软件不如基于开源免费工具自己搭一套 PDF 编辑转换工作台把文字、图片、链接编辑批注、签名、页面整理、格式转换和 OCR 都串起来。这篇文章会围绕“免费 可复用 可自动化”三条原则展开。先解释 PDF 为什么难编辑再给出图形工具和命令行工具的组合选型然后从环境准备开始带你完成页面整理、文字和图片插入、批注签名、格式转换、OCR 识别、批量处理这几个典型场景。最后会给出常见报错和排查路径方便你在自己机器上对照复现。1. 免费 PDF 编辑的核心先搞清楚 PDF 为什么难改1.1 PDF 的页面不是图层而是绘制指令很多人第一次接触 PDF 时会下意识把它当成一张“大图片”。正式来说PDF 是一种页面描述语言文件内部不是一张位图而是由一系列对象组成字典、数组、字符串、数字、流等。每个页面是一个页面对象页面的显示内容放在内容流中。内容流里记录的是“用某一种字体在某个坐标位置绘制某些字符”这样的指令而不是“这一页有一个标题段落”这样的结构化信息。所以在修改 PDF 前先要判断一个文件属于哪种类型类型特征后续处理方式文本型 PDF内容流中存在字体和字符指令可以被选择和复制可以尝试文字编辑、提取、转换扫描型 PDF页面主体是一张 JPEG 或 CCITT 图像没有可选中文字需要 OCR 识别先转成文字再编辑或搜索混合型 PDF部分是文字部分是图片常见于盖章后的合同按区域分别处理一页 PDF 里出现的“文字”可能是字符也可能是字体中的曲线路径还可能是扫描图片里的像素。三种情况的处理手段完全不同这也是很多免费工具“看起来能打开”却“不能编辑”的根源。1.2 编辑困难的原因主要有三层第一PDF 不保存文档结构。它没有“标题三号字”“正文小四字”“表格第三行”这类语义段落、表格、列表关系需要靠坐标和字体信息去反推。第二内容流中的绘制顺序不一定等于阅读顺序。一个页面可能先绘制背景图再绘制文字最后绘制水印也可能把一页内容拆成多个内容流。第三字体嵌入情况复杂。有的 PDF 只嵌入了字体子集字符 A 的内部编码可能是私有的直接替换文本很容易变成乱码。这三点决定了“直接修改 PDF 文字”和“用 Word 修改文字”完全不是一回事。如果你的需求只是改几个字免费图形工具可以应付如果要批量修改大量文档就必须用脚本按对象方式处理。所以我给出的方案不是某一个软件而是一个工具组合。1.3 免费 PDF 处理的六类需求根据标题里的功能可以拆成六类功能需求推荐免费工具自动化方式页面整理合并、拆分、旋转、重排PDF Arranger、qpdfpypdf / PyMuPDF文字、图片、链接编辑LibreOffice Draw、Master PDF Editor 免费版PyMuPDF批注、高亮、签名Xournal、PDF ArrangerPyMuPDF格式转换PDF 转 Word / 图片LibreOffice、pdf2imageLibreOffice 命令行OCR 识别Tesseract、PaddleOCRpytesseract / PaddleOCR API批量处理Python 脚本组装上面所有库的组合后面的内容会围绕这张表展开图形工具负责“人工精细操作”Python 脚本负责“批量、可重复、可追踪”的处理。两者结合基本可以覆盖日常办公和项目交付场景。2. 先选定工具组合再动手安装2.1 图形界面免费工具的选型对比如果你的需求是“打开一个 PDF手工改几处”没必要先写代码。先用图形工具解决问题更快。工具开源协议适用场景注意点LibreOffice DrawMPL导入 PDF 后可以拖动文字块、插入文本框和图形复杂排版会错位适合轻度修改PDF ArrangerGPL合并、拆分、旋转、删除、调整页面顺序只做页面级操作不做文字编辑XournalGPL手写批注、高亮、签名适合平板和鼠标批注Master PDF Editor 免费版自由软件但有商业授权条款可直接编辑文字、图片和链接免费版有水印或功能限制商用前看许可实际项目中我建议把 PDF Arranger 和 Xournal 作为“日常手工工具”LibreOffice Draw 作为“特殊排版时才用”的兜底工具。真正的高效流程往往是先用脚本批量处理再人工确认结果。2.2 命令行工具适合脚本调用命令行工具适合放进自动化和 CI 流程典型工具包括qpdf页面合并、拆分、旋转、加密、解密、检查 PDF 结构。GhostscriptPDF 转图片、压缩、修复破损 PDF。mutool来自 MuPDF 工具集可以转 PDF、检查内容流、提取文字。pdftoppm / pdfinfo来自 poppler 工具集转图片和查看信息。比如检查一个 PDF 是不是文本型可以直接用 pdfinfo 看 “Pages” 和文件属性用 pdftotext 试提取文字。pdfinfo sample.pdf pdftotext sample.pdf - | head -n 20如果 pdftotext 能输出文字说明文件里有文本层如果输出为空或乱码大概率是扫描型 PDF需要走 OCR。2.3 Python 库选型谁负责哪一层用 Python 处理 PDF 时选库第一原则是“按功能选而不是按名气选”。下面是一份可用参考库名代码引入名核心能力适合场景PyMuPDFpymupdf 或 fitz页面操作、文本插入、图片插入、批注、渲染图片、OCR 结果回填编辑和批注性能好pypdfpypdf合并、拆分、旋转、加密、元数据简单页面操作pdfplumberpdfplumber提取表格、文字、坐标解析结构化内容pdf2imagepdf2image把 PDF 页面转成 PIL 图片配合 OCRreportlabreportlab从零创建 PDF生成报表和票据python-docxdocx创建和修改 Word 文档OCR 结果输出到 Wordpytesseractpytesseract调用 Tesseract 引擎常规 OCRpaddleocrpaddleocr调用 PaddleOCR 引擎中文识别复杂版面其中 PyMuPDF 是这篇文章的主角。它既能读也能写还能在页面里插文字、插图片、加批注调用方便性能也比纯 Python 实现的库快不少。2.4 学习环境与生产环境的差距要提前知道学习环境里跑通一个脚本就够了。但生产环境还要考虑依赖版本锁定不能用最新版随缘安装。大文件处理时的临时文件和内存占用。输入文件是否带密码是否有权限限制。脚本执行日志和失败重试。是否要封装成 HTTP 服务供其他系统调用。下面从第 3 节开始按“学习环境快速跑通”为主线同时在关键位置说明生产环境需要注意什么。3. 环境准备Python、OCR 引擎和系统级依赖3.1 创建 Python 虚拟环境建议使用 Python 3.10 及以上版本。下面以 Windows 和 Linux/macOS 两种环境示例。python -m venv .venv激活虚拟环境# Linux / macOS source .venv/bin/activate # Windows PowerShell .venv\Scripts\Activate.ps1激活后执行 pip 安装。如果网络环境较慢可以加上国内镜像源这只是加速包下载不改变代码逻辑。pip install --upgrade pip pip install pymupdf pypdf pdfplumber pdf2image pillow python-docx pytesseract3.2 安装 Tesseract OCR 和 popplerpytesseract 只是一个 Python 调用层真正的识别引擎是 Tesseract。pdf2image 生成图片时需要 poppler 提供 pdftoppm 程序。各系统的安装方式不完全一样下面给出常见命令# Ubuntu / Debian sudo apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils # macOS brew install tesseract tesseract-lang poppler # Windows # 推荐使用包管理器安装安装后把 tesseract 和 poppler 的 bin 目录加入 PATHTesseract 默认只支持英文需要在安装时加上中文简体语言包。不同平台的包名可能略有差异以官方文档为准。安装完成后用命令行验证tesseract --version pdftoppm -v如果系统提示找不到命令说明 PATH 没有配置好。Windows 用户最容易掉进这个坑安装后要么重启终端要么手动设置环境变量。3.3 安装 PaddleOCR 中文识别引擎如果你的目标主要是中文扫描件PaddleOCR 的识别效果通常比 Tesseract 默认模型更好但安装更重因为需要安装 PaddlePaddle 深度学习框架。pip install paddlepaddle paddleocrPaddlePaddle 的版本和 Python 版本、CUDA 环境绑定较紧。学习环境建议直接安装 CPU 版先跑通流程有 GPU 且已配置 CUDA 的环境再根据官方文档安装对应 GPU 版本。安装完成后做一次最小调用确认依赖没有冲突。from paddleocr import PaddleOCR ocr PaddleOCR(langch) print(PaddleOCR ready)如果这一步报错多半是 paddlepaddle 和 paddleocr 版本不匹配先把两个库的版本都固定下来再统一升级或回退。3.4 安装 LibreOffice 用于格式转换PDF 转 Word 或 PDF 转文本时LibreOffice 是一个免费且可命令行调用的方案。安装后在 Linux/macOS 上通常可以直接执行sofficeWindows 上可能要用soffice.exe的完整路径。soffice --version需要注意LibreOffice 是“把 PDF 作为图形元素导入后重新导出为 Word”它不会恢复原始 Word 的样式复杂的表格和图文混排会明显错位。这个限制后面还会讲到。4. 页面整理合并、拆分、旋转和元数据修改4.1 合并多个 PDFpypdf 的最小脚本先实现一个最实用的场景把多个 PDF 按顺序合并成一个。新建 merge_pdfs.pyfrom pypdf import PdfReader, PdfWriter def merge_pdfs(file_list, output_path): writer PdfWriter() for file in file_list: reader PdfReader(file) for page in reader.pages: writer.add_page(page) with open(output_path, wb) as f: writer.write(f) if __name__ __main__: merge_pdfs([a.pdf, b.pdf, c.pdf], merged.pdf)这段代码的要点在于PdfReader负责读取PdfWriter只负责收集页面。如果输入文件有打开密码需要在读取前调用reader.decrypt(密码)否则会抛出解密相关异常。4.2 按指定范围拆分 PDF拆分比合并更常见。比如只需要某几页发给客户就直接按页数切出来from pypdf import PdfReader, PdfWriter start_page 2 # 起始页码从 1 开始 end_page 5 # 结束页码包含该页 reader PdfReader(demo.pdf) writer PdfWriter() for i in range(start_page - 1, min(end_page, len(reader.pages))): writer.add_page(reader.pages[i]) with open(part_2_5.pdf, wb) as f: writer.write(f)注意start_page - 1因为程序里的索引从 0 开始而人习惯从 1 开始。这是最容易写错的地方也是所有分页脚本最容易出 Bug 的源头。4.3 旋转页面和调整页面顺序pypdf 支持直接修改页面的rotation属性from pypdf import PdfReader, PdfWriter reader PdfReader(demo.pdf) writer PdfWriter() page writer.add_page(reader.pages[0]) page.rotate(90) with open(rotated.pdf, wb) as f: writer.write(f)rotate(90)会在现有角度上再旋转 90 度page.rotation 90是直接设置最终角度。在批量处理时要选一种统一使用否则同一批文件可能出现角度叠加。页面排序也很简单注意顺序按照目标文件中的页序传入writer PdfWriter() order [2, 0, 1] # 原第 3 页放到第一原第 1 页放第二 reader PdfReader(demo.pdf) for index in order: writer.add_page(reader.pages[index]) with open(reordered.pdf, wb) as f: writer.write(f)4.4 修改文档元数据元数据是 PDF 文件头部的一组键值对常见键是/Title、/Author、/Subject、/Keywords。修改时先读取原文件再把所有页面写入新 writer最后覆盖元数据from pypdf import PdfReader, PdfWriter reader PdfReader(demo.pdf) writer PdfWriter() for page in reader.pages: writer.add_page(page) writer.add_metadata({ /Title: 项目交付文档, /Author: 技术组, /Subject: 2025 年第一季度版本, }) with open(metadata.pdf, wb) as f: writer.write(f)生产环境里重要的是在批量处理前先统一元数据规范。否则最终交付的 1000 份文件文件属性各不相同后期做文档管理系统会很痛苦。5. 在 PDF 页面中插入文字、图片与链接5.1 用 PyMuPDF 插入文字页面整理类操作解决的是“页面级结构”真正往页面里添加内容推荐使用 PyMuPDF。下面这段代码在页面左上角插入一段文字import pymupdf # 较新版本也可以用 import fitz doc pymupdf.open(demo.pdf) page doc[0] page.insert_text( (72, 72), # 插入位置单位是 point PDF EDIT TEST, # 文本内容 fontsize14, # 字号 fontnamehelv, # 内置英文字体 color(0, 0, 1), # RGB 颜色这是蓝色 ) doc.save(with_text.pdf)字体参数fontnamehelv是 PDF 内置的 Helvetica 字体不需要额外加载字体文件。但注意它不支持中文。如果你要插入中文需要换用 PyMuPDF 自带的中文字体。page.insert_text( (72, 72), 这是一段中文测试, fontsize14, fontnamechina-s, # 简体中文内置字体 color(0, 0, 0), )china-s和china-t分别对应简体中文和繁体中文这是 PyMuPDF 内置的字体子集可以避免因为系统缺少字体而出现乱码。如果你需要自定义公司体或特殊字体需要先把字体文件交给工具这比用内置字体要复杂得多。5.2 插入图片水印、盖章和配图插入图片最典型的场景是给 PDF 加公司水印、贴电子章或加产品截图。import pymupdf doc pymupdf.open(demo.pdf) page doc[0] page.insert_image( pymupdf.Rect(72, 100, 200, 200), # 图片放置区域 filenamelogo.png, # 图片路径 overlayTrue, # True 表示浮在内容上层 ) doc.save(with_image.pdf)Rect(x0, y0, x1, y1)里的四个数字分别是矩形左上角和右下角的坐标。PyMuPDF 的页面坐标通常把左上角当原点x 轴向右y 轴向下这一点和电脑屏幕坐标一致比较容易理解。如果你使用底层 PDF 内容流处理还会碰到 PDF 原生坐标 y 轴向上那时候就很容易做反。5.3 插入超链接而不是只画一个“像链接”的文本有时候我们需要的不是可见文字而是一个可点击链接区域。page.insert_link({ kind: pymupdf.LINK_URI, from: pymupdf.Rect(72, 260, 220, 280), uri: https://example.com, })这样就在坐标区域内生成一个可点击的外部链接。要注意的是链接区域必须和可见文字的位置对齐。否则会肉眼看不到问题但鼠标点不准。5.4 插入文字、图片和链接时的常见误区第一个误区是盲目使用内置英文字体插入中文结果全是乱码。第二个误区是把文字坐标给错了导致文字重叠。第三个误区是批量加图片时没有考虑图片尺寸直接把图拉得严重变形。下面用一段代码说明如何避免变形from PIL import Image import pymupdf img Image.open(logo.png) box_w, box_h 200, 200 ratio min(box_w / img.width, box_h / img.height) final_w img.width * ratio final_h img.height * ratio x0 72 y0 100 page.insert_image( pymupdf.Rect(x0, y0, x0 final_w, y0 final_h), filenamelogo.png, )这样图片会按原始宽高比缩放不会变成“压扁的椭圆 logo”。6. 批注、高亮与电子签名6.1 给页面加高亮和批注批注场景中最常见的两个需求是给重点内容加高亮以及在某处附加文字说明。import pymupdf doc pymupdf.open(contract.pdf) page doc[0] # 高亮一段文字 page.add_highlight_annot(pymupdf.Rect(72, 100, 300, 120)) # 添加一个文字标注 annot page.add_text_annot((150, 200), 这一段需要确认) annot.set_colors(stroke(1, 0, 0)) annot.update() doc.save(annotated.pdf, garbage4, deflateTrue)这里garbage4表示在保存时清理未使用的对象deflateTrue表示压缩内容流。这两个参数配合起来能在一定程度上控制输出文件体积。如果省略这两个参数多次修改后的文件很容易越来越大最终给协作方传输时非常吃力。6.2 手写签名的落地方式电子签名在免费工具里最稳妥的方式是“签名图片 插入图片区域”。过程分三步在白纸上手写签名拍照。用图片处理工具把背景去掉导出透明背景 PNG。用insert_image把图放到 PDF 签名区域。page.insert_image( pymupdf.Rect(400, 600, 480, 640), filenamesignature.png, )这个方案有几个好处不依赖数据库不依赖云端证书文件长期有效任何人都能打开。缺点是签名图片可以被复制不适合对法律安全性要求极高的场景。如果要求防篡改需要接入数字签名或电子签章平台那是另一套技术路线。6.3 手工批注工具什么时候用 Python什么时候用 XournalPython 适合给大量 PDF 加统一批注比如“内部资料”水印、统一高亮条款、批量加日期。而人工判断的备注、审批意见、手写签名建议直接用 Xournal 这类绘图界面工具完成。两者不是替代关系而是分工关系。在批注流程里最容易被忽略的是“源文件备份”。PDF 一旦被保存修改原有对象顺序和内容流都可能发生变化很难无痕撤销。批量处理前先把原始文件单独放一个目录脚本只读源目录输出到新目录这样可以从源头避免覆盖事故。7. 格式转换与 OCR让扫描 PDF 变成可检索文档7.1 PDF 转图片留给后续 OCR 用如果已经把扫描版 PDF 拿到手OCR 前通常先按页面渲染成图片。渲染分辨率直接影响识别率一般建议 200 DPI 起步版面较小或文字较密的文件建议 300 DPI。pdftoppm -png -r 200 scan.pdf page这样会生成 page-1.png、page-2.png 等文件。用 Python 调用同样逻辑from pdf2image import convert_from_path images convert_from_path(scan.pdf, dpi200) for i, img in enumerate(images): img.save(fpage_{i 1}.png)7.2 多张图片合成 PDF反向场景也很常见多个盖章截图、多个现场照片需要合成一个 PDF 交付。from PIL import Image images [] for i in range(1, 11): img Image.open(fpage_{i}.png).convert(RGB) images.append(img) images[0].save(new.pdf, save_allTrue, append_imagesimages[1:])这里转成 RGB 模式很关键否则带透明通道的 PNG 在部分 PDF 阅读器里可能出现黑色背景。7.3 使用 Tesseract 识别文字最小示例安装好 Tesseract 后用 pytesseract 识别单张图片import pytesseract from PIL import Image text pytesseract.image_to_string( Image.open(page_1.png), langchi_simeng, ) print(text)langchi_simeng表示同时加载简体中文和英文语言包。如果只识别英文可以去掉 chi_sim识别速度会快一些。如果识别出来的中文全是乱码优先检查语言包是否安装成功而不是怀疑代码。7.4 使用 PaddleOCR 识别中文和复杂版面对中文报告的识别PaddleOCR 通常比 Tesseract 默认模型稳定。下面示例基于 PaddleOCR 3.x 的调用风格具体 API 以安装版本对应的官方文档为准from paddleocr import PaddleOCR ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationTrue, langch, ) result ocr.predict(inputpage_1.png) print(result[0].json)use_doc_orientation_classify负责判断文档方向use_doc_unwarping负责弯曲文档矫正use_textline_orientation负责行方向识别。普通扫描件可以只开行方向识别处理速度和稳定性更均衡。7.5 把 OCR 结果回填回 PDF生成可搜索 PDFOCR 的价值不只是拿到一个文本字符串而是要把识别文本放回原 PDF 对应位置这样用户搜索、复制、摘录时才像“真正的文字版 PDF”。关键是把图片像素坐标换算成 PDF 页面坐标。如果图片是通过pdftoppm -r 200生成的那么图片里的 1 个像素对应 PDF 中的 72 / 200 个 point。x 轴方向一致直接乘y 轴方向在 PyMuPDF 的页面坐标里也是从上往下所以同样按比例缩放。import pymupdf dpi 200 scale 72.0 / dpi x0_pdf 50 * scale y0_pdf 80 * scale doc pymupdf.open(scan.pdf) page doc[0] page.insert_text( (x0_pdf, y0_pdf), 这是 OCR 识别出的文字, fontsize12, fontnamechina-s, render_mode3, # 不可见文本用于搜索层 ) doc.save(searchable.pdf)实际项目中识别结果是一个个文字框而不是整段文字。正确做法是把识别出来的每个 block 或每个 text_line 的坐标都换算成 PDF 坐标再逐条插入。这样才能保证鼠标选中文字时选区位置和原图里的位置是对应的。这里的render_mode3让文本不显示在页面中但文本层仍然保留。这样页面视觉上还是原始扫描图但搜索和复制功能已经具备。不过不同查看器对不可见文本的处理并不完全一致交付前至少用 Adobe Reader 和 Chrome 预览各验证一次。7.6 PDF 转 Word免费方案能做到什么程度先给出命令soffice --headless --convert-to docx --outdir output_dir input.pdf这条命令会调用 LibreOffice 导入 PDF 并导出为 docx。优点是免费、离线、可批量。缺点也要先说清楚它重建的是“看起来相似”的文档不会恢复原始 Word 里的样式、目录、文本框关系。对于版面简单的 PDF效果可以接受对于多栏、表格复杂、图文混排的 PDF转换后往往需要大量人工调整。如果需要更可控的“PDF 转 Word”在 OCR 基础上可以自己生成 Word 文档。OCR 得到全文后用 python-docx 写入from docx import Document doc Document() doc.add_heading(识别结果, level0) with open(ocr_text.txt, r, encodingutf-8) as f: for line in f: doc.add_paragraph(line.strip()) doc.save(result.docx)这个方案不会保留原排版但好处是文本完全是结构化数据你可以自行决定段落层级。对合同文本提取、投标文件内容归档这类场景保留准确文本比恢复版面更重要。8. 批处理把零散脚本变成一条可复用工作流8.1 文件夹批量加水印单文件操作跑通后批量处理的价值才真正体现。下面这个脚本会遍历一个文件夹下所有 PDF统一在页面右上角添加水印文字并输出到新目录。from pathlib import Path import pymupdf def add_watermark_batch(input_dir, output_dir, watermark_text): input_dir Path(input_dir) output_dir Path(output_dir) output_dir.mkdir(parentsTrue, exist_okTrue) for pdf_path in input_dir.glob(*.pdf): doc pymupdf.open(pdf_path) for page in doc: page.insert_text( (page.rect.width - 180, 50), watermark_text, fontsize12, fontnamechina-s, color(0.5, 0.5, 0.5), ) out_path output_dir / fwm_{pdf_path.name} doc.save(str(out_path), garbage4, deflateTrue) doc.close() if __name__ __main__: add_watermark_batch(docs, docs_output, 内部资料请勿外传)目录遍历、文件保存、日志输出都要统一约定。生产环境不要直接覆盖源文件建议固定输入输出目录并保留一份处理日志方便排查为何某个文件没有输出。8.2 批处理中的日志与失败重试批量脚本最忌讳“跑了一上午最后发现第 3 个文件就报错了但程序没停下来”。可以先做“快速失败”加上日志和计数器import logging logging.basicConfig( levellogging.INFO, format%(asctime)s %(levelname)s %(message)s, handlers[ logging.FileHandler(batch.log), logging.StreamHandler(), ], ) def process_one(path): # 单个文件的处理逻辑 pass failed [] for pdf_path in input_dir.glob(*.pdf): try: process_one(pdf_path) logging.info(fok: {pdf_path.name}) except Exception as exc: logging.exception(ffail: {pdf_path.name}: {exc}) failed.append(pdf_path.name) if failed: logging.warning(ffailed files: {failed})这样处理完一批文件后至少知道哪些文件失败、失败原因是什么、从哪一步开始恢复。8.3 用命令行封装完整处理链路如果你需要把 OCR、转换、加水印串起来推荐写成 Makefile 或 Shell 脚本。下面是一个简化示例说明处理流程#!/bin/bash INPUT_DIR./input OUTPUT_DIR./output mkdir -p $OUTPUT_DIR for pdf in $INPUT_DIR/*.pdf; do name$(basename $pdf .pdf) python convert_pdf_to_images.py $pdf $OUTPUT_DIR/${name}_page.png python run_ocr.py $OUTPUT_DIR/${name}_page.png $OUTPUT_DIR/${name}_text.json python write_back_text.py $pdf $OUTPUT_DIR/${name}_text.json $OUTPUT_DIR/${name}_searchable.pdf done脚本本身没有复杂度核心是把每一步结果清晰落盘。这样某个环节出错时上一环节的中间产物还在不用整条链路重跑。9. 常见问题与排查路径9.1 中文文字变成乱码现象用insert_text插入中文后打开 PDF 显示成方块或乱码。可能原因使用fontnamehelv插入中文。系统缺少中文字体PyMuPDF 找不到可用的字体回退方案。检查方式看看代码里fontname参数是否写成了英文字体。打开 PDF看看是显示为空白、方块还是错字。解决办法page.insert_text((72, 72), 中文内容, fontnamechina-s)预防建议在团队代码里封装一个统一函数固定中文插入使用china-s避免其他人随手写成helv。9.2 OCR 识别结果大段乱码现象文字基本能识别但夹杂大量口语、错字或者完全乱码。可能原因图片分辨率低于 150 DPI。图片倾斜、模糊。语言包只装了英文没装中文。图片中存在表格、旋转文字等复杂版面。检查方式先在图片查看器里肉眼判断清晰度。运行tesseract --list-langs查看是否包含chi_sim。用单一页面先做实验再批量处理。解决办法重新渲染 PDFDPI 提到 300。用 OpenCV 或 PaddleOCR 的方向分类先矫正。确认语言包安装完整。9.3 PDF 转 Word 后表格全乱现象转换后文字能编辑但表格、双栏内容完全错位。原因不是工具坏了而是 LibreOffice 的 PDF 导入机制决定的。PDF 不保留表格结构工具只能根据坐标重建表格复杂的合并单元格和多层表头很容易重建失败。处理方式对纯文本资料接受“内容保留、样式简化”的结果。对必须还原表格的文档先用 pdfplumber 解析表格再把数据写入 docx 表格。对扫描件走 OCR 后按段落重建而不是直接转 Word。9.4 带密码的 PDF 无法处理现象脚本读取文件时提示加密或操作被禁止。先判断是有打开密码还是有权限密码。打开密码需要用户输入权限密码限制打印、复制等操作。两种密码作用不同代码处理方式也不同。只能用合法的授权方式不能绕过密码限制。如果你对文件本身拥有权限并且清楚密码可以使用from pypdf import PdfReader reader PdfReader(protected.pdf) if reader.is_encrypted: reader.decrypt(你的密码)再一次提醒这里只适用于你自己有权访问的文档不能用于未授权破解。9.5 处理超大 PDF 时内存暴涨现象一个 500 MB 的 PDF脚本运行到一半内存占满程序被系统杀掉。原因某些库会把整个 PDF 文件加载进内存或者批量处理时文档对象没有及时释放。检查方式任务管理器或 top 命令观察内存曲线。看代码里是否在循环内累积了很多 Page 对象。解决办法每次处理完一个 PDF 就doc.close()。如果只取部分页面先拆分原文件成几个小文件再逐批处理。优先用 PyMuPDF 读取文件对象而不是把整个文件先读成 bytes。doc pymupdf.open(large.pdf) # 处理当前文档 doc.close()9.6 添加内容后为什么文件体积突然变大现象只加了一个文字水印文件从 2 MB 变成 50 MB。原因默认保存时没有清除冗余对象也没有压缩内容流或者插入了超大图片。解决办法使用doc.save(out.pdf, garbage4, deflateTrue)。插入图片前先用 Pillow 统一压缩到合适尺寸。批量处理时记录处理前后体积设置体积异常告警。10. 从免费工具到工程化最佳实践与扩展方向10.1 处理 PDF 前必查的三个问题任何脚本处理前先检查三件事可以省下大量排错时间文件是文本型还是扫描型用pdftotext或 pdfplumber 试提取前几页。文件是否加密用pdfinfo查看读取阶段正确处理密码。文件的内部版本和标准是否需要支持 PDF/A是否包含特殊表单字段。10.2 学习环境与生产环境的差异维度学习环境生产环境依赖版本直接安装最新版锁定 requirements.txt 或固定版本文件存储本地路径对象存储、临时目录自动清理日志终端 print结构化日志记录文件名、耗时、失败原因并发单文件顺序处理按 CPU 核数或任务队列限流安全不考虑权限控制、脱敏、文件访问审计回滚覆盖源文件版本化管理输出独立目录10.3 建议固定的工程规范源文件、中间文件、输出文件分三个目录存放。每次处理前生成一次文件清单处理完成后比对输出数量。对 OCR 结果单独保存 JSON方便后面重建索引。所有批量任务必须能“断点续跑”不做半途而废的脚本。10.4 扩展方向从 PDF 工具到 OCR 知识库当 PDF 处理能力稳定后下一个值得尝试的方向是把识别结果接入知识库系统。比如把合同 PDF 转成结构化文本写入向量数据库再做语义检索或者把发票、单据这类固定版式文档通过 PaddleOCR 提取关键字段自动录入业务系统。典型链路是PDF 解析 - 图片渲染 - OCR 识别 - 文本后处理 - 结构化存储 - 检索或表单自动填充这条链路里每一步都可以独立验证。跑通单页再跑通批量再接入业务系统。不要在第一步还没稳定时就直接对接生产数据。如果你是从零开始学习建议按这个顺序练习先掌握 pypdf 的页面操作再掌握 PyMuPDF 的插入和批注再上手 Tesseract 的简单 OCR最后切换到 PaddleOCR 处理复杂中文版面。每一层都能独立产出可交付结果整个技能树会搭得非常稳。 免费PDF编辑转换工作台：从零搭建开源工具链
在实际办公和工程文档处理中PDF 的定位一直是“最终交付格式”而不是“可编辑格式”。要把合同里的错别字改掉、给扫描件加上可检索文字、把十几份 PDF 合成一个归档文件很多人第一反应是打开在线转换站。但上传大文件、隐私文件、批量素材时传输和调用次数又成为新的瓶颈。与其到处找收费 PDF 软件不如基于开源免费工具自己搭一套 PDF 编辑转换工作台把文字、图片、链接编辑批注、签名、页面整理、格式转换和 OCR 都串起来。这篇文章会围绕“免费 可复用 可自动化”三条原则展开。先解释 PDF 为什么难编辑再给出图形工具和命令行工具的组合选型然后从环境准备开始带你完成页面整理、文字和图片插入、批注签名、格式转换、OCR 识别、批量处理这几个典型场景。最后会给出常见报错和排查路径方便你在自己机器上对照复现。1. 免费 PDF 编辑的核心先搞清楚 PDF 为什么难改1.1 PDF 的页面不是图层而是绘制指令很多人第一次接触 PDF 时会下意识把它当成一张“大图片”。正式来说PDF 是一种页面描述语言文件内部不是一张位图而是由一系列对象组成字典、数组、字符串、数字、流等。每个页面是一个页面对象页面的显示内容放在内容流中。内容流里记录的是“用某一种字体在某个坐标位置绘制某些字符”这样的指令而不是“这一页有一个标题段落”这样的结构化信息。所以在修改 PDF 前先要判断一个文件属于哪种类型类型特征后续处理方式文本型 PDF内容流中存在字体和字符指令可以被选择和复制可以尝试文字编辑、提取、转换扫描型 PDF页面主体是一张 JPEG 或 CCITT 图像没有可选中文字需要 OCR 识别先转成文字再编辑或搜索混合型 PDF部分是文字部分是图片常见于盖章后的合同按区域分别处理一页 PDF 里出现的“文字”可能是字符也可能是字体中的曲线路径还可能是扫描图片里的像素。三种情况的处理手段完全不同这也是很多免费工具“看起来能打开”却“不能编辑”的根源。1.2 编辑困难的原因主要有三层第一PDF 不保存文档结构。它没有“标题三号字”“正文小四字”“表格第三行”这类语义段落、表格、列表关系需要靠坐标和字体信息去反推。第二内容流中的绘制顺序不一定等于阅读顺序。一个页面可能先绘制背景图再绘制文字最后绘制水印也可能把一页内容拆成多个内容流。第三字体嵌入情况复杂。有的 PDF 只嵌入了字体子集字符 A 的内部编码可能是私有的直接替换文本很容易变成乱码。这三点决定了“直接修改 PDF 文字”和“用 Word 修改文字”完全不是一回事。如果你的需求只是改几个字免费图形工具可以应付如果要批量修改大量文档就必须用脚本按对象方式处理。所以我给出的方案不是某一个软件而是一个工具组合。1.3 免费 PDF 处理的六类需求根据标题里的功能可以拆成六类功能需求推荐免费工具自动化方式页面整理合并、拆分、旋转、重排PDF Arranger、qpdfpypdf / PyMuPDF文字、图片、链接编辑LibreOffice Draw、Master PDF Editor 免费版PyMuPDF批注、高亮、签名Xournal、PDF ArrangerPyMuPDF格式转换PDF 转 Word / 图片LibreOffice、pdf2imageLibreOffice 命令行OCR 识别Tesseract、PaddleOCRpytesseract / PaddleOCR API批量处理Python 脚本组装上面所有库的组合后面的内容会围绕这张表展开图形工具负责“人工精细操作”Python 脚本负责“批量、可重复、可追踪”的处理。两者结合基本可以覆盖日常办公和项目交付场景。2. 先选定工具组合再动手安装2.1 图形界面免费工具的选型对比如果你的需求是“打开一个 PDF手工改几处”没必要先写代码。先用图形工具解决问题更快。工具开源协议适用场景注意点LibreOffice DrawMPL导入 PDF 后可以拖动文字块、插入文本框和图形复杂排版会错位适合轻度修改PDF ArrangerGPL合并、拆分、旋转、删除、调整页面顺序只做页面级操作不做文字编辑XournalGPL手写批注、高亮、签名适合平板和鼠标批注Master PDF Editor 免费版自由软件但有商业授权条款可直接编辑文字、图片和链接免费版有水印或功能限制商用前看许可实际项目中我建议把 PDF Arranger 和 Xournal 作为“日常手工工具”LibreOffice Draw 作为“特殊排版时才用”的兜底工具。真正的高效流程往往是先用脚本批量处理再人工确认结果。2.2 命令行工具适合脚本调用命令行工具适合放进自动化和 CI 流程典型工具包括qpdf页面合并、拆分、旋转、加密、解密、检查 PDF 结构。GhostscriptPDF 转图片、压缩、修复破损 PDF。mutool来自 MuPDF 工具集可以转 PDF、检查内容流、提取文字。pdftoppm / pdfinfo来自 poppler 工具集转图片和查看信息。比如检查一个 PDF 是不是文本型可以直接用 pdfinfo 看 “Pages” 和文件属性用 pdftotext 试提取文字。pdfinfo sample.pdf pdftotext sample.pdf - | head -n 20如果 pdftotext 能输出文字说明文件里有文本层如果输出为空或乱码大概率是扫描型 PDF需要走 OCR。2.3 Python 库选型谁负责哪一层用 Python 处理 PDF 时选库第一原则是“按功能选而不是按名气选”。下面是一份可用参考库名代码引入名核心能力适合场景PyMuPDFpymupdf 或 fitz页面操作、文本插入、图片插入、批注、渲染图片、OCR 结果回填编辑和批注性能好pypdfpypdf合并、拆分、旋转、加密、元数据简单页面操作pdfplumberpdfplumber提取表格、文字、坐标解析结构化内容pdf2imagepdf2image把 PDF 页面转成 PIL 图片配合 OCRreportlabreportlab从零创建 PDF生成报表和票据python-docxdocx创建和修改 Word 文档OCR 结果输出到 Wordpytesseractpytesseract调用 Tesseract 引擎常规 OCRpaddleocrpaddleocr调用 PaddleOCR 引擎中文识别复杂版面其中 PyMuPDF 是这篇文章的主角。它既能读也能写还能在页面里插文字、插图片、加批注调用方便性能也比纯 Python 实现的库快不少。2.4 学习环境与生产环境的差距要提前知道学习环境里跑通一个脚本就够了。但生产环境还要考虑依赖版本锁定不能用最新版随缘安装。大文件处理时的临时文件和内存占用。输入文件是否带密码是否有权限限制。脚本执行日志和失败重试。是否要封装成 HTTP 服务供其他系统调用。下面从第 3 节开始按“学习环境快速跑通”为主线同时在关键位置说明生产环境需要注意什么。3. 环境准备Python、OCR 引擎和系统级依赖3.1 创建 Python 虚拟环境建议使用 Python 3.10 及以上版本。下面以 Windows 和 Linux/macOS 两种环境示例。python -m venv .venv激活虚拟环境# Linux / macOS source .venv/bin/activate # Windows PowerShell .venv\Scripts\Activate.ps1激活后执行 pip 安装。如果网络环境较慢可以加上国内镜像源这只是加速包下载不改变代码逻辑。pip install --upgrade pip pip install pymupdf pypdf pdfplumber pdf2image pillow python-docx pytesseract3.2 安装 Tesseract OCR 和 popplerpytesseract 只是一个 Python 调用层真正的识别引擎是 Tesseract。pdf2image 生成图片时需要 poppler 提供 pdftoppm 程序。各系统的安装方式不完全一样下面给出常见命令# Ubuntu / Debian sudo apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils # macOS brew install tesseract tesseract-lang poppler # Windows # 推荐使用包管理器安装安装后把 tesseract 和 poppler 的 bin 目录加入 PATHTesseract 默认只支持英文需要在安装时加上中文简体语言包。不同平台的包名可能略有差异以官方文档为准。安装完成后用命令行验证tesseract --version pdftoppm -v如果系统提示找不到命令说明 PATH 没有配置好。Windows 用户最容易掉进这个坑安装后要么重启终端要么手动设置环境变量。3.3 安装 PaddleOCR 中文识别引擎如果你的目标主要是中文扫描件PaddleOCR 的识别效果通常比 Tesseract 默认模型更好但安装更重因为需要安装 PaddlePaddle 深度学习框架。pip install paddlepaddle paddleocrPaddlePaddle 的版本和 Python 版本、CUDA 环境绑定较紧。学习环境建议直接安装 CPU 版先跑通流程有 GPU 且已配置 CUDA 的环境再根据官方文档安装对应 GPU 版本。安装完成后做一次最小调用确认依赖没有冲突。from paddleocr import PaddleOCR ocr PaddleOCR(langch) print(PaddleOCR ready)如果这一步报错多半是 paddlepaddle 和 paddleocr 版本不匹配先把两个库的版本都固定下来再统一升级或回退。3.4 安装 LibreOffice 用于格式转换PDF 转 Word 或 PDF 转文本时LibreOffice 是一个免费且可命令行调用的方案。安装后在 Linux/macOS 上通常可以直接执行sofficeWindows 上可能要用soffice.exe的完整路径。soffice --version需要注意LibreOffice 是“把 PDF 作为图形元素导入后重新导出为 Word”它不会恢复原始 Word 的样式复杂的表格和图文混排会明显错位。这个限制后面还会讲到。4. 页面整理合并、拆分、旋转和元数据修改4.1 合并多个 PDFpypdf 的最小脚本先实现一个最实用的场景把多个 PDF 按顺序合并成一个。新建 merge_pdfs.pyfrom pypdf import PdfReader, PdfWriter def merge_pdfs(file_list, output_path): writer PdfWriter() for file in file_list: reader PdfReader(file) for page in reader.pages: writer.add_page(page) with open(output_path, wb) as f: writer.write(f) if __name__ __main__: merge_pdfs([a.pdf, b.pdf, c.pdf], merged.pdf)这段代码的要点在于PdfReader负责读取PdfWriter只负责收集页面。如果输入文件有打开密码需要在读取前调用reader.decrypt(密码)否则会抛出解密相关异常。4.2 按指定范围拆分 PDF拆分比合并更常见。比如只需要某几页发给客户就直接按页数切出来from pypdf import PdfReader, PdfWriter start_page 2 # 起始页码从 1 开始 end_page 5 # 结束页码包含该页 reader PdfReader(demo.pdf) writer PdfWriter() for i in range(start_page - 1, min(end_page, len(reader.pages))): writer.add_page(reader.pages[i]) with open(part_2_5.pdf, wb) as f: writer.write(f)注意start_page - 1因为程序里的索引从 0 开始而人习惯从 1 开始。这是最容易写错的地方也是所有分页脚本最容易出 Bug 的源头。4.3 旋转页面和调整页面顺序pypdf 支持直接修改页面的rotation属性from pypdf import PdfReader, PdfWriter reader PdfReader(demo.pdf) writer PdfWriter() page writer.add_page(reader.pages[0]) page.rotate(90) with open(rotated.pdf, wb) as f: writer.write(f)rotate(90)会在现有角度上再旋转 90 度page.rotation 90是直接设置最终角度。在批量处理时要选一种统一使用否则同一批文件可能出现角度叠加。页面排序也很简单注意顺序按照目标文件中的页序传入writer PdfWriter() order [2, 0, 1] # 原第 3 页放到第一原第 1 页放第二 reader PdfReader(demo.pdf) for index in order: writer.add_page(reader.pages[index]) with open(reordered.pdf, wb) as f: writer.write(f)4.4 修改文档元数据元数据是 PDF 文件头部的一组键值对常见键是/Title、/Author、/Subject、/Keywords。修改时先读取原文件再把所有页面写入新 writer最后覆盖元数据from pypdf import PdfReader, PdfWriter reader PdfReader(demo.pdf) writer PdfWriter() for page in reader.pages: writer.add_page(page) writer.add_metadata({ /Title: 项目交付文档, /Author: 技术组, /Subject: 2025 年第一季度版本, }) with open(metadata.pdf, wb) as f: writer.write(f)生产环境里重要的是在批量处理前先统一元数据规范。否则最终交付的 1000 份文件文件属性各不相同后期做文档管理系统会很痛苦。5. 在 PDF 页面中插入文字、图片与链接5.1 用 PyMuPDF 插入文字页面整理类操作解决的是“页面级结构”真正往页面里添加内容推荐使用 PyMuPDF。下面这段代码在页面左上角插入一段文字import pymupdf # 较新版本也可以用 import fitz doc pymupdf.open(demo.pdf) page doc[0] page.insert_text( (72, 72), # 插入位置单位是 point PDF EDIT TEST, # 文本内容 fontsize14, # 字号 fontnamehelv, # 内置英文字体 color(0, 0, 1), # RGB 颜色这是蓝色 ) doc.save(with_text.pdf)字体参数fontnamehelv是 PDF 内置的 Helvetica 字体不需要额外加载字体文件。但注意它不支持中文。如果你要插入中文需要换用 PyMuPDF 自带的中文字体。page.insert_text( (72, 72), 这是一段中文测试, fontsize14, fontnamechina-s, # 简体中文内置字体 color(0, 0, 0), )china-s和china-t分别对应简体中文和繁体中文这是 PyMuPDF 内置的字体子集可以避免因为系统缺少字体而出现乱码。如果你需要自定义公司体或特殊字体需要先把字体文件交给工具这比用内置字体要复杂得多。5.2 插入图片水印、盖章和配图插入图片最典型的场景是给 PDF 加公司水印、贴电子章或加产品截图。import pymupdf doc pymupdf.open(demo.pdf) page doc[0] page.insert_image( pymupdf.Rect(72, 100, 200, 200), # 图片放置区域 filenamelogo.png, # 图片路径 overlayTrue, # True 表示浮在内容上层 ) doc.save(with_image.pdf)Rect(x0, y0, x1, y1)里的四个数字分别是矩形左上角和右下角的坐标。PyMuPDF 的页面坐标通常把左上角当原点x 轴向右y 轴向下这一点和电脑屏幕坐标一致比较容易理解。如果你使用底层 PDF 内容流处理还会碰到 PDF 原生坐标 y 轴向上那时候就很容易做反。5.3 插入超链接而不是只画一个“像链接”的文本有时候我们需要的不是可见文字而是一个可点击链接区域。page.insert_link({ kind: pymupdf.LINK_URI, from: pymupdf.Rect(72, 260, 220, 280), uri: https://example.com, })这样就在坐标区域内生成一个可点击的外部链接。要注意的是链接区域必须和可见文字的位置对齐。否则会肉眼看不到问题但鼠标点不准。5.4 插入文字、图片和链接时的常见误区第一个误区是盲目使用内置英文字体插入中文结果全是乱码。第二个误区是把文字坐标给错了导致文字重叠。第三个误区是批量加图片时没有考虑图片尺寸直接把图拉得严重变形。下面用一段代码说明如何避免变形from PIL import Image import pymupdf img Image.open(logo.png) box_w, box_h 200, 200 ratio min(box_w / img.width, box_h / img.height) final_w img.width * ratio final_h img.height * ratio x0 72 y0 100 page.insert_image( pymupdf.Rect(x0, y0, x0 final_w, y0 final_h), filenamelogo.png, )这样图片会按原始宽高比缩放不会变成“压扁的椭圆 logo”。6. 批注、高亮与电子签名6.1 给页面加高亮和批注批注场景中最常见的两个需求是给重点内容加高亮以及在某处附加文字说明。import pymupdf doc pymupdf.open(contract.pdf) page doc[0] # 高亮一段文字 page.add_highlight_annot(pymupdf.Rect(72, 100, 300, 120)) # 添加一个文字标注 annot page.add_text_annot((150, 200), 这一段需要确认) annot.set_colors(stroke(1, 0, 0)) annot.update() doc.save(annotated.pdf, garbage4, deflateTrue)这里garbage4表示在保存时清理未使用的对象deflateTrue表示压缩内容流。这两个参数配合起来能在一定程度上控制输出文件体积。如果省略这两个参数多次修改后的文件很容易越来越大最终给协作方传输时非常吃力。6.2 手写签名的落地方式电子签名在免费工具里最稳妥的方式是“签名图片 插入图片区域”。过程分三步在白纸上手写签名拍照。用图片处理工具把背景去掉导出透明背景 PNG。用insert_image把图放到 PDF 签名区域。page.insert_image( pymupdf.Rect(400, 600, 480, 640), filenamesignature.png, )这个方案有几个好处不依赖数据库不依赖云端证书文件长期有效任何人都能打开。缺点是签名图片可以被复制不适合对法律安全性要求极高的场景。如果要求防篡改需要接入数字签名或电子签章平台那是另一套技术路线。6.3 手工批注工具什么时候用 Python什么时候用 XournalPython 适合给大量 PDF 加统一批注比如“内部资料”水印、统一高亮条款、批量加日期。而人工判断的备注、审批意见、手写签名建议直接用 Xournal 这类绘图界面工具完成。两者不是替代关系而是分工关系。在批注流程里最容易被忽略的是“源文件备份”。PDF 一旦被保存修改原有对象顺序和内容流都可能发生变化很难无痕撤销。批量处理前先把原始文件单独放一个目录脚本只读源目录输出到新目录这样可以从源头避免覆盖事故。7. 格式转换与 OCR让扫描 PDF 变成可检索文档7.1 PDF 转图片留给后续 OCR 用如果已经把扫描版 PDF 拿到手OCR 前通常先按页面渲染成图片。渲染分辨率直接影响识别率一般建议 200 DPI 起步版面较小或文字较密的文件建议 300 DPI。pdftoppm -png -r 200 scan.pdf page这样会生成 page-1.png、page-2.png 等文件。用 Python 调用同样逻辑from pdf2image import convert_from_path images convert_from_path(scan.pdf, dpi200) for i, img in enumerate(images): img.save(fpage_{i 1}.png)7.2 多张图片合成 PDF反向场景也很常见多个盖章截图、多个现场照片需要合成一个 PDF 交付。from PIL import Image images [] for i in range(1, 11): img Image.open(fpage_{i}.png).convert(RGB) images.append(img) images[0].save(new.pdf, save_allTrue, append_imagesimages[1:])这里转成 RGB 模式很关键否则带透明通道的 PNG 在部分 PDF 阅读器里可能出现黑色背景。7.3 使用 Tesseract 识别文字最小示例安装好 Tesseract 后用 pytesseract 识别单张图片import pytesseract from PIL import Image text pytesseract.image_to_string( Image.open(page_1.png), langchi_simeng, ) print(text)langchi_simeng表示同时加载简体中文和英文语言包。如果只识别英文可以去掉 chi_sim识别速度会快一些。如果识别出来的中文全是乱码优先检查语言包是否安装成功而不是怀疑代码。7.4 使用 PaddleOCR 识别中文和复杂版面对中文报告的识别PaddleOCR 通常比 Tesseract 默认模型稳定。下面示例基于 PaddleOCR 3.x 的调用风格具体 API 以安装版本对应的官方文档为准from paddleocr import PaddleOCR ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationTrue, langch, ) result ocr.predict(inputpage_1.png) print(result[0].json)use_doc_orientation_classify负责判断文档方向use_doc_unwarping负责弯曲文档矫正use_textline_orientation负责行方向识别。普通扫描件可以只开行方向识别处理速度和稳定性更均衡。7.5 把 OCR 结果回填回 PDF生成可搜索 PDFOCR 的价值不只是拿到一个文本字符串而是要把识别文本放回原 PDF 对应位置这样用户搜索、复制、摘录时才像“真正的文字版 PDF”。关键是把图片像素坐标换算成 PDF 页面坐标。如果图片是通过pdftoppm -r 200生成的那么图片里的 1 个像素对应 PDF 中的 72 / 200 个 point。x 轴方向一致直接乘y 轴方向在 PyMuPDF 的页面坐标里也是从上往下所以同样按比例缩放。import pymupdf dpi 200 scale 72.0 / dpi x0_pdf 50 * scale y0_pdf 80 * scale doc pymupdf.open(scan.pdf) page doc[0] page.insert_text( (x0_pdf, y0_pdf), 这是 OCR 识别出的文字, fontsize12, fontnamechina-s, render_mode3, # 不可见文本用于搜索层 ) doc.save(searchable.pdf)实际项目中识别结果是一个个文字框而不是整段文字。正确做法是把识别出来的每个 block 或每个 text_line 的坐标都换算成 PDF 坐标再逐条插入。这样才能保证鼠标选中文字时选区位置和原图里的位置是对应的。这里的render_mode3让文本不显示在页面中但文本层仍然保留。这样页面视觉上还是原始扫描图但搜索和复制功能已经具备。不过不同查看器对不可见文本的处理并不完全一致交付前至少用 Adobe Reader 和 Chrome 预览各验证一次。7.6 PDF 转 Word免费方案能做到什么程度先给出命令soffice --headless --convert-to docx --outdir output_dir input.pdf这条命令会调用 LibreOffice 导入 PDF 并导出为 docx。优点是免费、离线、可批量。缺点也要先说清楚它重建的是“看起来相似”的文档不会恢复原始 Word 里的样式、目录、文本框关系。对于版面简单的 PDF效果可以接受对于多栏、表格复杂、图文混排的 PDF转换后往往需要大量人工调整。如果需要更可控的“PDF 转 Word”在 OCR 基础上可以自己生成 Word 文档。OCR 得到全文后用 python-docx 写入from docx import Document doc Document() doc.add_heading(识别结果, level0) with open(ocr_text.txt, r, encodingutf-8) as f: for line in f: doc.add_paragraph(line.strip()) doc.save(result.docx)这个方案不会保留原排版但好处是文本完全是结构化数据你可以自行决定段落层级。对合同文本提取、投标文件内容归档这类场景保留准确文本比恢复版面更重要。8. 批处理把零散脚本变成一条可复用工作流8.1 文件夹批量加水印单文件操作跑通后批量处理的价值才真正体现。下面这个脚本会遍历一个文件夹下所有 PDF统一在页面右上角添加水印文字并输出到新目录。from pathlib import Path import pymupdf def add_watermark_batch(input_dir, output_dir, watermark_text): input_dir Path(input_dir) output_dir Path(output_dir) output_dir.mkdir(parentsTrue, exist_okTrue) for pdf_path in input_dir.glob(*.pdf): doc pymupdf.open(pdf_path) for page in doc: page.insert_text( (page.rect.width - 180, 50), watermark_text, fontsize12, fontnamechina-s, color(0.5, 0.5, 0.5), ) out_path output_dir / fwm_{pdf_path.name} doc.save(str(out_path), garbage4, deflateTrue) doc.close() if __name__ __main__: add_watermark_batch(docs, docs_output, 内部资料请勿外传)目录遍历、文件保存、日志输出都要统一约定。生产环境不要直接覆盖源文件建议固定输入输出目录并保留一份处理日志方便排查为何某个文件没有输出。8.2 批处理中的日志与失败重试批量脚本最忌讳“跑了一上午最后发现第 3 个文件就报错了但程序没停下来”。可以先做“快速失败”加上日志和计数器import logging logging.basicConfig( levellogging.INFO, format%(asctime)s %(levelname)s %(message)s, handlers[ logging.FileHandler(batch.log), logging.StreamHandler(), ], ) def process_one(path): # 单个文件的处理逻辑 pass failed [] for pdf_path in input_dir.glob(*.pdf): try: process_one(pdf_path) logging.info(fok: {pdf_path.name}) except Exception as exc: logging.exception(ffail: {pdf_path.name}: {exc}) failed.append(pdf_path.name) if failed: logging.warning(ffailed files: {failed})这样处理完一批文件后至少知道哪些文件失败、失败原因是什么、从哪一步开始恢复。8.3 用命令行封装完整处理链路如果你需要把 OCR、转换、加水印串起来推荐写成 Makefile 或 Shell 脚本。下面是一个简化示例说明处理流程#!/bin/bash INPUT_DIR./input OUTPUT_DIR./output mkdir -p $OUTPUT_DIR for pdf in $INPUT_DIR/*.pdf; do name$(basename $pdf .pdf) python convert_pdf_to_images.py $pdf $OUTPUT_DIR/${name}_page.png python run_ocr.py $OUTPUT_DIR/${name}_page.png $OUTPUT_DIR/${name}_text.json python write_back_text.py $pdf $OUTPUT_DIR/${name}_text.json $OUTPUT_DIR/${name}_searchable.pdf done脚本本身没有复杂度核心是把每一步结果清晰落盘。这样某个环节出错时上一环节的中间产物还在不用整条链路重跑。9. 常见问题与排查路径9.1 中文文字变成乱码现象用insert_text插入中文后打开 PDF 显示成方块或乱码。可能原因使用fontnamehelv插入中文。系统缺少中文字体PyMuPDF 找不到可用的字体回退方案。检查方式看看代码里fontname参数是否写成了英文字体。打开 PDF看看是显示为空白、方块还是错字。解决办法page.insert_text((72, 72), 中文内容, fontnamechina-s)预防建议在团队代码里封装一个统一函数固定中文插入使用china-s避免其他人随手写成helv。9.2 OCR 识别结果大段乱码现象文字基本能识别但夹杂大量口语、错字或者完全乱码。可能原因图片分辨率低于 150 DPI。图片倾斜、模糊。语言包只装了英文没装中文。图片中存在表格、旋转文字等复杂版面。检查方式先在图片查看器里肉眼判断清晰度。运行tesseract --list-langs查看是否包含chi_sim。用单一页面先做实验再批量处理。解决办法重新渲染 PDFDPI 提到 300。用 OpenCV 或 PaddleOCR 的方向分类先矫正。确认语言包安装完整。9.3 PDF 转 Word 后表格全乱现象转换后文字能编辑但表格、双栏内容完全错位。原因不是工具坏了而是 LibreOffice 的 PDF 导入机制决定的。PDF 不保留表格结构工具只能根据坐标重建表格复杂的合并单元格和多层表头很容易重建失败。处理方式对纯文本资料接受“内容保留、样式简化”的结果。对必须还原表格的文档先用 pdfplumber 解析表格再把数据写入 docx 表格。对扫描件走 OCR 后按段落重建而不是直接转 Word。9.4 带密码的 PDF 无法处理现象脚本读取文件时提示加密或操作被禁止。先判断是有打开密码还是有权限密码。打开密码需要用户输入权限密码限制打印、复制等操作。两种密码作用不同代码处理方式也不同。只能用合法的授权方式不能绕过密码限制。如果你对文件本身拥有权限并且清楚密码可以使用from pypdf import PdfReader reader PdfReader(protected.pdf) if reader.is_encrypted: reader.decrypt(你的密码)再一次提醒这里只适用于你自己有权访问的文档不能用于未授权破解。9.5 处理超大 PDF 时内存暴涨现象一个 500 MB 的 PDF脚本运行到一半内存占满程序被系统杀掉。原因某些库会把整个 PDF 文件加载进内存或者批量处理时文档对象没有及时释放。检查方式任务管理器或 top 命令观察内存曲线。看代码里是否在循环内累积了很多 Page 对象。解决办法每次处理完一个 PDF 就doc.close()。如果只取部分页面先拆分原文件成几个小文件再逐批处理。优先用 PyMuPDF 读取文件对象而不是把整个文件先读成 bytes。doc pymupdf.open(large.pdf) # 处理当前文档 doc.close()9.6 添加内容后为什么文件体积突然变大现象只加了一个文字水印文件从 2 MB 变成 50 MB。原因默认保存时没有清除冗余对象也没有压缩内容流或者插入了超大图片。解决办法使用doc.save(out.pdf, garbage4, deflateTrue)。插入图片前先用 Pillow 统一压缩到合适尺寸。批量处理时记录处理前后体积设置体积异常告警。10. 从免费工具到工程化最佳实践与扩展方向10.1 处理 PDF 前必查的三个问题任何脚本处理前先检查三件事可以省下大量排错时间文件是文本型还是扫描型用pdftotext或 pdfplumber 试提取前几页。文件是否加密用pdfinfo查看读取阶段正确处理密码。文件的内部版本和标准是否需要支持 PDF/A是否包含特殊表单字段。10.2 学习环境与生产环境的差异维度学习环境生产环境依赖版本直接安装最新版锁定 requirements.txt 或固定版本文件存储本地路径对象存储、临时目录自动清理日志终端 print结构化日志记录文件名、耗时、失败原因并发单文件顺序处理按 CPU 核数或任务队列限流安全不考虑权限控制、脱敏、文件访问审计回滚覆盖源文件版本化管理输出独立目录10.3 建议固定的工程规范源文件、中间文件、输出文件分三个目录存放。每次处理前生成一次文件清单处理完成后比对输出数量。对 OCR 结果单独保存 JSON方便后面重建索引。所有批量任务必须能“断点续跑”不做半途而废的脚本。10.4 扩展方向从 PDF 工具到 OCR 知识库当 PDF 处理能力稳定后下一个值得尝试的方向是把识别结果接入知识库系统。比如把合同 PDF 转成结构化文本写入向量数据库再做语义检索或者把发票、单据这类固定版式文档通过 PaddleOCR 提取关键字段自动录入业务系统。典型链路是PDF 解析 - 图片渲染 - OCR 识别 - 文本后处理 - 结构化存储 - 检索或表单自动填充这条链路里每一步都可以独立验证。跑通单页再跑通批量再接入业务系统。不要在第一步还没稳定时就直接对接生产数据。如果你是从零开始学习建议按这个顺序练习先掌握 pypdf 的页面操作再掌握 PyMuPDF 的插入和批注再上手 Tesseract 的简单 OCR最后切换到 PaddleOCR 处理复杂中文版面。每一层都能独立产出可交付结果整个技能树会搭得非常稳。