PyMuPDF+python-docx实现离线PDF转DOCX-北京尧图网络

简介这是一款基于Python开发的轻量级PDF转Word桌面工具面向Windows办公用户及轻量文档处理需求者解决PDF文件难以直接编辑的核心痛点。工具支持单文件、多文件及整文件夹批量转换操作极简——解压即运行pdf2doc.exe无需安装依赖、无广告、无捆绑已在Windows 10/11系统实测可用。资源包共1154个文件主体为可执行程序exe、Python编译模块pyd、动态链接库dll及本地化时区数据文件如gmt、tzdata相关qm/tcl/xml等体现其内嵌完整PDF解析与DOCX生成能力压缩包大小105.54MB结构紧凑适配离线环境使用。目前已有142人下载学习用户可直接获得开箱即用的转换工具、配套时区资源集及稳定可靠的自用级实现逻辑特别适合需高频处理PDF文档但不愿依赖在线服务或付费软件的办公人员与技术爱好者。1. 为什么一个“双击就能用”的 PDF 转 DOC 工具反而比在线转换更值得你本地部署你有没有过这种经历临时要交一份合同扫描件的可编辑版打开浏览器搜“PDF转Word免费”点进第3个网站上传、等待、弹出广告、再点“下载”结果下下来的却是带水印的 DOCX或者格式错乱到表格全飞、页眉消失、中文字体变方块更糟的是那份PDF里有客户名称、报价明细——你刚把它传给了一个连域名都拼不全的第三方网站。这个标题说的不是某个商业软件的精简版也不是调用某云API的GUI包装器而是一个完全离线、无网络请求、不依赖Office套件、Windows原生兼容、解压即用的 Python 打包产物pdf2doc.exe。它背后是PyMuPDFfitz python-docx的轻量组合绕开了 Windows COM 自动化不卡死、不报错“Word未响应”也避开了pdfplumberpandas那套重解析逻辑不崩内存、不丢中文。它解决的不是“能不能转”而是“能不能在领导催稿的凌晨两点双击一下3秒出干净DOCX且敢直接发给法务审”。适合两类人一是行政/法务/教务等高频处理扫描件但无IT支持的岗位二是开发者想嵌入自有工具链又不想被 Office 版本、许可证、后台进程拖累。这不是玩具脚本是我在某高校教务系统对接项目里为批量处理历年纸质成绩单扫描件打磨出的落地方案。2. 为什么选 PyMuPDF 而不是 pdfminer 或 tabula核心原理与选型血泪经验2.1 PDF 文本提取的三种路径谁在“看”谁在“猜”谁在“重建”PDF 本质是绘图指令流不是文本容器。所谓“转 Word”其实是三类技术路线的博弈OCR 路径如 Tesseract pdf2image把每页 PDF 渲染成图片再识别文字。优点是能处理纯扫描件缺点是慢单页2秒起、依赖图像质量、中文识别率波动大、无法保留原始字体/颜色/超链接。本方案明确排除此路径——标题强调“亲测 Windows 10/11 可用”而 OCR 需额外安装 Tesseract 和图像库违背“解压即用”原则。文本流解析路径如 pdfminer、pdfplumber逐字读取 PDF 内嵌的文本操作符Tj, TJ按坐标聚合成段落。优点是快、纯文本精准缺点是面对 Adobe Acrobat 生成的“伪PDF”实际是图片透明文字层、或加了文字混淆的 PDF 时坐标错乱、顺序颠倒、中英文混排断行失效。我曾用 pdfminer 处理某法院文书 PDF结果“原告张三”被拆成两行“”字单独占一行——因为它的文本块坐标 Y 值差了 0.3pt。渲染级重建路径PyMuPDF / fitz本方案唯一选择。它不解析文本流而是调用 MuPDF 引擎C 库将 PDF精确渲染为矢量图层文本层混合对象再通过page.get_text(dict)获取带位置、字体、大小、颜色的结构化文本块。关键在于它能区分“真实文本”和“伪装文本”如扫描件上叠加的 OCR 层并默认跳过图像区域。更重要的是它对中文 PDF 的 Unicode 处理极稳定——不依赖系统字体映射自带 CJK 字体回退机制。提示PyMuPDF 是目前 Windows 下唯一能在无管理员权限、无 Visual Studio 运行库、无 Office 安装前提下稳定提取 PDF 文本图像元数据的 Python 库。其fitz模块编译后体积仅 8MB远小于poppler全家桶。2.2 为什么 DOCX 生成不用 python-docx 的“模板填充”而用“段落级重建”python-docx常见用法是打开模板.docx替换占位符。但本方案要求“零依赖”不能预置模板文件。因此采用底层构造法from docx import Document from docx.shared import Pt, RGBColor from docx.enum.text import WD_PARAGRAPH_ALIGNMENT doc Document() # 不用 add_heading() 或 add_paragraph() 的默认样式 # 而是手动控制每个段落的字体、大小、对齐 p doc.add_paragraph() p.alignment WD_PARAGRAPH_ALIGNMENT.LEFT run p.add_run(这是第一行文本) run.font.size Pt(12) run.font.color.rgb RGBColor(0, 0, 0)这样做的好处是完全规避 Word 样式继承污染。比如某 PDF 中标题用黑体 16pt正文用宋体 10.5pt若用模板填充Word 会强行把所有内容套进模板的“正文”样式导致字号统一缩水。而段落级重建让每个run对象直接受控于 PDF 原始文本块的fontname和size字段实现像素级还原。2.3 为什么打包成 .exe 而非 .pywPyInstaller 的三个关键参数.exe文件本质是 PyInstaller 将 Python 解释器、依赖库、源码打包后的自解压可执行体。但默认打包会失败——因为 PyMuPDF 的fitz动态库_fitz.pyd路径在运行时不可见。必须显式指定pyinstaller --onefile --windowed --add-binary C:\Python39\Lib\site-packages\fitz\_fitz.pyd;fitz --hidden-import fitz pdf2doc.py--add-binary强制将_fitz.pyd及其所在目录fitz打包进 EXE 的虚拟文件系统并确保运行时sys._MEIPASS能定位到它。漏掉这句EXE 启动必报ImportError: DLL load failed。--windowed隐藏命令行黑窗口。否则双击运行时会先弹 CMD 窗口用户误以为卡死。--hidden-import fitzPyInstaller 静态分析无法识别import fitz因fitz是 C 扩展模块别名必须手动声明否则打包后import fitz报错。最终生成的pdf2doc.exe体积约 32MB含 Python 解释器但启动速度 0.5 秒比调用 COM 接口的 Word 自动化快 10 倍以上。3. 从源码到 EXE完整构建流程与可复现的最小代码集3.1 核心转换逻辑57 行 Python 实现 PDF 到 DOCX 的结构化映射以下代码是pdf2doc.py的主体已剔除日志、GUI、异常美化等非核心逻辑保留最简可用路径# pdf2doc.py import sys import os from pathlib import Path import fitz # PyMuPDF from docx import Document from docx.shared import Pt, RGBColor, Inches from docx.enum.text import WD_PARAGRAPH_ALIGNMENT from docx.oxml.ns import qn from docx.oxml import OxmlElement def pdf_to_docx(pdf_path: str, docx_path: str): doc Document() # 设置默认页面边距适配 A4 sections doc.sections for section in sections: section.left_margin Inches(1.0) section.right_margin Inches(1.0) section.top_margin Inches(1.0) section.bottom_margin Inches(1.0) doc.styles[Normal].font.name SimSun # 中文默认宋体 doc.styles[Normal]._element.rPr.rFonts.set(qn(w:eastAsia), SimSun) pdf_doc fitz.open(pdf_path) for page_num in range(len(pdf_doc)): page pdf_doc[page_num] # 获取页面文本块带位置、字体、大小信息 blocks page.get_text(dict)[blocks] for b in blocks: if b[type] 0: # 文本块 for line in b[lines]: for span in line[spans]: # 创建新段落 p doc.add_paragraph() p.alignment WD_PARAGRAPH_ALIGNMENT.LEFT run p.add_run(span[text]) # 映射字体大小PDF 中单位是 pt直接赋值 run.font.size Pt(max(8, min(72, int(span[size])))) # 字体名称映射简化版中文字体优先用 SimSun英文字体用 Times New Roman font_name span[font] if any(c in font_name for c in [Sim, Fang, Kai, Hei, Song]): run.font.name SimSun run._element.rPr.rFonts.set(qn(w:eastAsia), SimSun) else: run.font.name Times New Roman # 颜色PDF 中是 (r,g,b) 归一化值转为 0-255 r, g, b [int(c * 255) for c in span[color]] run.font.color.rgb RGBColor(r, g, b) doc.save(docx_path) pdf_doc.close() if __name__ __main__: if len(sys.argv) ! 2: print(Usage: pdf2doc.exe input.pdf) sys.exit(1) input_pdf sys.argv[1] if not input_pdf.lower().endswith(.pdf): print(Error: Input file must be a PDF.) sys.exit(1) output_docx str(Path(input_pdf).with_suffix(.docx)) try: pdf_to_docx(input_pdf, output_docx) print(f✅ Converted: {input_pdf} → {output_docx}) except Exception as e: print(f❌ Failed: {str(e)}) sys.exit(1)逻辑说明与参数深挖page.get_text(dict)返回的是嵌套字典blocks是页面内所有文本/图像块的列表。b[type] 0过滤出纯文本块1是图像块本方案暂不处理图像插入只提取文字。span[size]是 PDF 中定义的字体大小单位 pt直接传给Pt()构造器。但需做边界限制max(8, min(72, ...))防止 PDF 中错误标注size0.1导致 Word 崩溃或size999导致段落撑满整页。字体映射用span[font]字符串粗筛含SimSimSun、FangFangSong等关键词则设为宋体否则设为 Times New Roman。不依赖系统字体是否存在——python-docx会静默降级不影响生成。颜色处理PDF 中span[color]是(r,g,b)归一化浮点元组如(0.2, 0.5, 0.8)乘以 255 转为整数再传给RGBColor。这是保证颜色不失真的关键一步。3.2 构建环境Python 3.9 是唯一验证通过的版本不要用 Python 3.11PyMuPDF 官方 wheel 目前2024Q2仅提供至 Python 3.10 的预编译包且 3.11 的 ABI 兼容性未测试。实测 Python 3.9.13 是最稳组合# 推荐使用独立虚拟环境避免污染全局 python -m venv pdf2doc_env pdf2doc_env\Scripts\activate.bat # 升级 pip 并安装核心依赖注意必须用官方 wheel禁用 --no-binary pip install --upgrade pip pip install PyMuPDF1.23.24 python-docx0.8.11 # 验证安装 python -c import fitz; print(fitz.__version__) # 输出 1.23.24 python -c from docx import Document; print(OK)PyMuPDF1.23.24此版本修复了 Windows 下多线程 PDF 打开崩溃问题某教务系统需并发处理 200 PDF。python-docx0.8.11最新版修复了 DOCX 中中文字体eastAsia属性写入 bug旧版会导致 Word 打开提示“文件已损坏”。3.3 打包命令详解为什么必须用--add-binary而非--collect-all# ❌ 错误--collect-all fitz 会收集整个 site-packages/fitz/但 _fitz.pyd 在子目录 pyinstaller --onefile --windowed --collect-all fitz pdf2doc.py # ✅ 正确精确定位 _fitz.pyd 并声明其虚拟路径 pyinstaller --onefile --windowed ^ --add-binary C:\path\to\python\Lib\site-packages\fitz\_fitz.pyd;fitz ^ --hidden-import fitz ^ pdf2doc.py--add-binary参数格式为源路径;目标虚拟目录。_fitz.pyd必须放在fitz目录下因为 PyMuPDF 源码中硬编码了import fitz._fitz。若只放_fitz.pyd在根目录运行时报ModuleNotFoundError: No module named fitz._fitz。打包后检查dist/pdf2doc.exe是否真包含该文件用 7-Zip 打开 EXE进入fitz/目录应能看到_fitz.pyd。这是验证打包成功的黄金标准。4. 常见问题排查那些让你怀疑人生、重启三次才找到原因的坑4.1 现象双击pdf2doc.exe无反应任务管理器里看不到进程原因--windowed参数生效但程序在初始化阶段抛出未捕获异常如fitz加载失败导致进程瞬间退出无任何提示。解决临时去掉--windowed用命令行运行pdf2doc.exe input.pdf观察 CMD 窗口输出的报错。90% 是ImportError: DLL load failed指向_fitz.pyd路径问题。检查--add-binary中的源路径是否真实存在且_fitz.pyd文件未被杀毒软件隔离。4.2 现象转换后 DOCX 中文全部显示为“□□□”英文正常原因python-docx未正确设置东亚字体eastAsia导致 Word 使用默认西文字体渲染中文。解决在Document()初始化后必须显式设置样式字体doc.styles[Normal].font.name SimSun doc.styles[Normal]._element.rPr.rFonts.set(qn(w:eastAsia), SimSun)漏掉第二行set(qn(w:eastAsia), ...)是新手最高频失误。font.name只控制西文eastAsia才管中文。4.3 现象PDF 中的加粗/斜体在 DOCX 中丢失原因PDF 中的字体风格Bold/Italic不体现在span[font]字符串里而是在span[flags]整数位掩码中。flags 16表示粗体flags 2表示斜体。解决在run p.add_run(...)后添加if span[flags] 16: run.bold True if span[flags] 2: run.italic True否则所有文字都是常规体格式信息永久丢失。4.4 现象转换后段落间距极大一页 PDF 变三页 DOCX原因PDF 中文本块的y1底部Y坐标和y0顶部Y坐标差值被误认为段落高度而python-docx默认段落间距为 12pt。解决禁用自动段落间距改用space_before/space_after精确控制p doc.add_paragraph() p.paragraph_format.space_before Pt(0) p.paragraph_format.space_after Pt(0) p.paragraph_format.line_spacing 1.0并在循环外统一设置doc.styles[Normal].paragraph_format.line_spacing 1.0。4.5 现象处理含中文路径的 PDF 时报错UnicodeEncodeError: mbcs codec cant encode characters原因Windows 控制台默认编码mbcsANSI无法处理 UTF-8 路径。解决在if __name__ __main__:开头强制设置控制台编码import locale locale.setlocale(locale.LC_ALL, Chinese_China.936) # 或直接用 chs或更通用的import sys if sys.stdout.encoding ! utf-8: sys.stdout.reconfigure(encodingutf-8)需 Python 3.75. 进阶技巧如何让 DOCX 保留 PDF 的页眉页脚、表格结构与超链接5.1 页眉页脚用page.get_text(dict)提取再注入 DOCX SectionPDF 的页眉页脚并非独立对象而是分散在页面顶部/底部的文本块。策略是统计所有文本块的y0顶部坐标取最小的 5% 作为“页眉区域”最大的 5% 作为“页脚区域”。def extract_headers_footers(blocks, page_height: float): header_texts, footer_texts [], [] y0s [b[bbox][1] for b in blocks if b[type] 0] # 所有文本块顶部Y if not y0s: return header_texts, footer_texts y0s_sorted sorted(y0s) header_threshold y0s_sorted[int(len(y0s_sorted) * 0.05)] # 前5%最小Y footer_threshold y0s_sorted[int(len(y0s_sorted) * 0.95)] # 后5%最大Y for b in blocks: if b[type] 0: y0 b[bbox][1] text .join([line[spans][0][text] for line in b[lines] if line[spans]]) if y0 header_threshold and text.strip(): header_texts.append(text.strip()) elif y0 footer_threshold and text.strip(): footer_texts.append(text.strip()) return list(dict.fromkeys(header_texts)), list(dict.fromkeys(footer_texts)) # 注入 DOCX 页眉需在 doc.add_section() 后操作 section doc.sections[0] header section.header header_para header.paragraphs[0] if header.paragraphs else header.add_paragraph() header_para.text | .join(extract_headers_footers(blocks, page.rect.height)[0])注意python-docx的页眉页脚是 Section 级别不是 Page 级别。若 PDF 每页页眉不同需为每页创建新 Sectiondoc.add_section(WD_SECTION.NEW_PAGE)否则只能提取第一页的页眉。5.2 表格结构用page.find_tables()替代纯文本提取PyMuPDF 1.22 新增page.find_tables()方法能识别 PDF 中的表格线框并返回结构化数据tables page.find_tables() for table in tables: # table.extract() 返回二维列表每行为一行数据 for row in table.extract(): # 创建 DOCX 表格行 doc_table doc.add_table(rows1, colslen(row)) doc_table.style Table Grid hdr_cells doc_table.rows[0].cells for i, cell_text in enumerate(row): hdr_cells[i].text cell_text但注意此方法对“无边框表格”仅靠空格对齐无效且对合并单元格支持有限。建议作为文本提取的补充而非替代——先用get_text(dict)提取全文再用find_tables()提取表格最后将表格内容按坐标插入到对应段落位置。5.3 超链接从page.get_links()提取并转换为 DOCX 超链接PDF 中的链接是独立对象不在文本块中links page.get_links() for link in links: if link[uri]: # 是网页链接 # 在文本块中查找坐标重叠的段落插入超链接 for b in blocks: if b[type] 0: bbox b[bbox] # (x0,y0,x1,y1) # 判断链接矩形是否与文本块矩形重叠 if (link[from].x0 bbox[2] and link[from].x1 bbox[0] and link[from].y0 bbox[3] and link[from].y1 bbox[1]): # 找到对应段落在其中插入超链接 p doc.paragraphs[-1] # 简化假设在最后一段 run p.add_run() run.hyperlink link[uri]实际项目中我用了一个更鲁棒的匹配遍历所有span计算其 bbox 与link[from]的 IOU交并比IOU 0.3 则视为该链接属于此文本。5.4 最终打包优化用 UPX 压缩 EXE体积从 32MB 降到 12MBUPX 是开源的可执行文件压缩器对 PyInstaller 打包的 EXE 兼容性极好# 下载 UPX 4.0.2 Windows 版https://upx.github.io/ upx --best --ultra-brute dist/pdf2doc.exe实测压缩率 62%且解压速度极快不影响启动性能。某教务系统部署时12MB 的 EXE 比 32MB 更易通过邮件附件发送也减少终端用户下载等待。我坚持在每个项目交付前用同一台 Win10 笔记本无 Office、无管理员权限、杀毒软件全开从零解压、双击、拖入 PDF、等待 3 秒、打开 DOCX 验证——这才是“亲测可用”的唯一标准。很多方案倒在“第一次运行就报错”而真正的工程化是让错误发生在构建阶段pyinstaller报错而不是用户双击之后。如果你也厌倦了每次转换都要祈祷、截图、重试不妨就用这 57 行核心代码搭一个真正属于自己的、不联网、不弹窗、不求人的 PDF 转 DOCX 黑匣子。希望帮到你。本文还有配套的精品资源点击获取

PyMuPDF+python-docx实现离线PDF转DOCX

相关推荐

工控与路由设备主动式安全基线探针插件集

游戏AI实战：实时推理、多模态闭环与低延迟决策引擎

Agent应用开发实战：从核心架构到多Agent协作的完整学习路径

更多资讯

psql-srv 深入解析：用 Rust 模拟 PostgreSQL 服务器，让现有应用零改动接入你的缓存层

医学图像格式转换全指南：RGB、灰度与索引的底层逻辑

NSL-KDD联邦入侵检测工程落地避坑指南

Linux终端复用工具 screen 详解：SSH断线任务不丢失

相交链表详解：从暴力到双指针，彻底吃透链表算法面试题

Scrapy Shell调试技巧：提升爬虫开发效率的交互式工具

今日更新

声子晶体仿真：三角晶格与六角晶格的能带计算实战

度假村安保定岗定编：岗位梳理、编制测算与排班设计

COMSOL等离子体模块实战：氩气双层DBD仿真建模全解析

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？