简介：面向软件开发、数据处理与自动化办公人群的 Word 文档解析实操资源包，覆盖 .doc/.docx 格式差异、OPC 包装结构、解压 XML 的解析流程，以及 python-docx、lxml 等常用库的使用，并给出可直接复用的代码示例。资源共 29 个文件，包含 4 个 Java 源码、6 个 XML 文件、1 个 docx 测试文档、1 个 jar 依赖、8 张 png 界面或结果截图，以及工程配置和文本说明，压缩包整体仅 1.79 MB。包内以 Android 工程示例呈现完整实现，从 AndroidManifest、源码、资源文件到 libs 依赖均有覆盖，附 Readme 和源码说明，便于对照检查解析逻辑与运行配置；讲解也涉及了格式兼容性、图片页眉页脚处理、样式保留等常见注意事项。目前已有 301 人学习，内容不算大而全，但过程拆解详细，适合想要快速落地 Word 文档解析与自动化处理的开发者参考。
1. 解析 Word 文档：为什么你收藏过的那些教程代码，真到入库时总缺几列
“解析 word 文档”听起来门槛不高，但真拿去处理真实文件，最常见的结果是：教程能读纯文本，却读不出表格；能数出段落数量，却拿不到标题层级；能在本地跑通示例，却没法直接改成批量任务。来回折腾几次后你会得出一个结论，这类“代码可直接复用”的教程，真正能复用的往往只有前面的十几行。问题多半不是代码写得不好，而是大家低估了 Word 的内部结构：它不是一个纯文本文件，而是一个需要按容器、正文、样式、嵌入内容逐层拆解的复合文档。
这篇笔记从一次实际需求切入，把某公司的产品说明书批量转成结构化数据，用可复制的 Python 代码把解析这件事讲透。适合新手直接抄回去做自动提取任务，也适合熟手在参数层做二次改造。整套设计思路会按四步展开：读结构、抽文本、拆复杂内容、做异常兜底，每步都会留下一个独立函数，让你看完就能拼出自己的解析工具包。
2. 打开 Word 文档的黑匣子：docx 内部结构、方案选型和遍历骨架
2.1 用几行代码验证：docx 其实是一个 ZIP 包
先纠正一个重要认知：扩展名是 .docx 的文件，并不是一个从第 3 行开始直接排文本的文本文件，而是一个 ZIP 压缩包，内部按固定目录存放了若干 XML 和媒体文件。正文放在 word/document.xml，样式、编号、超链接各自有独立部件，图片放在 word/media/ 目录下。只要拿到 docx 的物理结构，就能理解后续所有解析行为。
验证这个结论很简单，不需要任何第三方库，标准库 zipfile 就够了：
import zipfile def inspect_docx(path: str) -> list[str]: """把 docx 当成 ZIP 包打开，返回内部文件路径清单。 返回结果里如果包含 word/document.xml，基本可以断定是合法 docx。 """ with zipfile.ZipFile(path) as z: return z.namelist() if __name__ == "__main__": files = inspect_docx("sample.docx") for name in files: print(name)逻辑说明：zipfile.ZipFile 直接打开 docx 文件，namelist() 返回压缩包内全部成员路径。执行后你会看到类似 word/document.xml、word/media/image1.png 这样的输出。如果抛 BadZipFile 异常，说明文件本身不是标准的 docx，需要先走格式转换流程。
参数修改思路：只关心正文时，可以在返回列表中过滤“word/document.xml”这个成员；想检查有没有嵌入字体，就找 fonts 目录。这个函数适合作为所有解析任务的前置体检。
2.2 方案对比：为什么我默认用 python-docx，而不是自己拼 XML
在真实任务里，最稳妥的实现路径是站在现成解析库的肩膀上，而不是直接对 document.xml 做字符串切割。直接解析 XML 虽然能拿到最全的信息，但你会被命名空间前缀、空标签、属性顺序这些细节缠住，写出来的正则和 XPath 换一份文档就可能失效。
我一般默认用 python-docx 这个 Python 生态常用的 Word 解析库。它把 document.xml 里最常用的两类块级对象，段落和表格，封装成了可以直接遍历的 Python 对象；字符级样式、字体、对齐方式也能通过属性访问。常见替代方案是专门抽纯文本的工具，只适合做全文索引，一旦涉及表格结构或样式归属就不够用。
| 方案 | 正文文本 | 表格结构 | 段落/字符样式 | 上手成本 | 适用场景 |
|---|---|---|---|---|---|
| python-docx | 完整支持 | 完整支持 | 较完整 | 低 | 信息抽取、结构化入库 |
| 纯文本抽取库 | 完整支持 | 不完整 | 不支持 | 极低 | 全文检索、快速预览 |
| 直接解析 XML | 可自己写 | 可自己写 | 可自己写 | 高 | 特殊标记、标准库不覆盖的需求 |
python-docx 不是银弹，但它是多数场景下性价比最高的平衡点。后面所有代码都基于它展开，只有遇到它覆盖不了的内容时，我们的解析程序再回落到 ZIP + XML 层面。
2.3 按文档顺序遍历段落和表格：一个真正能做的骨架
新手最容易踩的坑是同时使用 doc.paragraphs 和 doc.tables 去还原原文顺序。这两个属性一个返回全部段落，一个返回全部表格，但它们的顺序是“先全部段落，再全部表格”，完全丢失了文档本身的交错顺序。文档里若出现“一段文字、一个表格、再一段文字”，这种读法会彻底打乱内容。
解决这个问题要回到库的内部模型。Document 的正文 XML 节点下，段落和表格按照它们在文档中的出现顺序平铺排列。按这个顺序逐个判断节点类型，就能还原原始阅读顺序：
from docx import Document from docx.oxml.table import CT_Tbl from docx.oxml.text.paragraph import CT_P from docx.table import Table from docx.text.paragraph import Paragraph def iter_block_items(doc): """按正文出现顺序返回段落或表格对象，还原 Word 原始阅读顺序。""" for child in doc.element.body.iterchildren(): if isinstance(child, CT_P): yield Paragraph(child, doc) elif isinstance(child, CT_Tbl): yield Table(child, doc) if __name__ == "__main__": doc = Document("sample.docx") for block in iter_block_items(doc): if isinstance(block, Paragraph): print(f"[段落] {block.text[:40]}") elif isinstance(block, Table): print(f"[表格] {len(block.rows)} 行 x {len(block.columns)} 列")逻辑说明：doc.element.body 是正文 XML 根节点，iterchildren() 按子节点顺序遍历；遇到 CT_P 就包装成 Paragraph，遇到 CT_Tbl 就包装成 Table。这段代码是你后文所有解析函数的地基，顺序还原、段落表格同排、复杂文档内容定位都依赖它。
参数修改思路：如果只想统计，可以在分支里直接累计计数；如果想输出结构化内容，可以在分支里挂上你自己的处理函数。注意 yield 的方式是惰性生成，处理大文档时比一次性收集所有对象更省内存。
3. 最快拿到正文：最小可复用代码与两个自定义参数
3.1 安装与版本验证：用几分钟排除环境问题
代码复用之前，先让环境跑通。python-docx 的安装路径只有一条命令，但不同机器上 Python 版本混用容易装错地方，所以我习惯用 python -m pip 而不是裸 pip：
python -m pip install python-docx装完后立刻验证版本和基本导入是否正常：
python -c "import docx; print(docx.__version__)"这个验证非常便宜，却能在最早阶段暴露两个常见问题：包没装进当前解释器，或者装成了其他同名模块。输出版本号后，环境部分就算过关。
提示：python-docx 只能处理基于 Open XML 标准的 .docx 文件。如果你手头只有旧版 .doc 二进制格式，直接传路径一定会失败，需要先用 Office 或 WPS 另存为 .docx，这在后面常见问题章节还会展开讲。
3.2 提取纯文本的最小函数：段落之间换行分隔
第一个可直接抄走的功能，是把整份 docx 的正文文字提取成一段纯文本。适用场景非常广：生成摘要、全文检索、做语言模型的输入预处理，都只需要这一步。代码可以压到很短：
from docx import Document def extract_text(path: str) -> str: """提取 docx 正文纯文本，段落之间用换行分隔。""" doc = Document(path) lines = [] for p in doc.paragraphs: if p.text.strip(): lines.append(p.text.strip()) return "\n".join(lines) if __name__ == "__main__": print(extract_text("sample.docx"))逻辑说明：Document(path) 一次性打开文件并完成正文解析；doc.paragraphs 返回正文主体中的全部段落，注意它不含表格里的文字；p.text 是段落内所有 run 文本自动拼接后的结果；strip() 去掉首尾空白后，再用换行把非空段落拼起来，输出结果可以直接写入 txt 文件。
参数修改思路：想保留空行做段落定位，就把 if 判断去掉；想同时提取表格文字，就不能用 doc.paragraphs 了，要改成第 2.3 节的 iter_block_items 骨架。纯文本模式最大的价值是“先拿到内容”，后续字段级定位靠下一节。
3.3 保留段落序号和样式信息：给字段级提取留退路
纯文本适合全文检索，但不适合做结构化入库。入库通常需要知道某段文字是什么角色，是标题、正文、还是落款。这时需要在提取时记录段落序号、样式名、加粗状态。下面这份函数可以直接替换 3.2 节里的提取逻辑：
from docx import Document def extract_paragraphs_with_style(path: str) -> list[dict]: """返回段落级结构化信息：序号、文本、样式名、是否存在加粗。""" doc = Document(path) result = [] for idx, p in enumerate(doc.paragraphs, start=1): if not p.text.strip(): continue item = { "index": idx, "text": p.text.strip(), "style_name": p.style.name if p.style else "Normal", "has_bold": any(r.bold for r in p.runs if r.text.strip()), } result.append(item) return result逻辑说明：enumerate 从 1 开始给段落编号，方便后续和原文对照；p.style.name 取值如 Title、Heading 1、Normal，是识别标题层级最直接的线索；any(r.bold for r in p.runs if r.text.strip()) 的作用是判断该段落内是否存在非空文本且加粗的 run。这里的加粗判断是“段落内存在粗体”，不是“整段粗体”，做标题候选识别时足够用。
参数修改思路：把 has_bold 换成对字体颜色、字号、下划线的判断，就能用于“提取红色标注文字”这类定制需求；把 style_name 按“Heading”开头的字段过滤，就能快速拿到目录结构。这套返回值可以直接转成 JSON 交给下游程序。
4. 表格、图片、页眉页脚的解析：三种最容易漏数据的区域
4.1 表格解析时处理合并单元格的默认逻辑
表格是 Word 解析里最容易出错的结构。因为表格看起来是“行 x 列”的二维网格，但在 Word 内部，每个单元格有自己的 XML 坐标，合并单元格会使 row.cells 返回重复对象：横向合并时，同一逻辑单元格会出现在一行里的多个位置。如果不去重，读出来的数据列数会凭空变多。
以下代码先做基础提取，再按位置去重：
from docx import Document def extract_tables(path: str) -> list[list[list[str]]]: """提取所有表格，三维数组结构：表格 -> 行 -> 单元格。""" doc = Document(path) all_tables = [] for table in doc.tables: table_data = [] for row in table.rows: row_data = [] seen = set() for cell in row.cells: # 合并单元格会让同一对象出现多次，只保留首次出现的位置 if id(cell) in seen: continue seen.add(id(cell)) text = " ".join(p.text.strip() for p in cell.paragraphs if p.text.strip()) row_data.append(text) table_data.append(row_data) all_tables.append(table_data) return all_tables逻辑说明：doc.tables 是正文中的所有表格；row.cells 会按网格位置返回单元格对象，合并单元格导致同一个对象被引用多次，用 id() 去重是简单有效的兜底策略；单元格内部可能有多段文本，用生成器把它们拼成一个字符串，避免漏数据。这个方法牺牲了“单元格准确跨行/列信息”，但换来了“行列整齐的纯数据视图”。
参数修改思路：需要保留单元格内换行时，把 join 的分隔符改成 " | " 或 "\n"；需要同时知道单元格坐标，就需要解析表格 XML 中的 tc 节点和 gridSpan，不建议在列表层面硬猜。
4.2 图片导出到本地目录：不依赖额外库的方案
招投标文件、产品说明书里，图片往往比正文更有价值。python-docx 没有直接提供一个“导出全部图片”的接口，但图片作为嵌入资源保存在 docx 包内，可以通过文档的关系表逐个取出来：
from docx import Document from pathlib import Path def extract_images(path: str, out_dir: str = "./images") -> list[str]: """把 docx 中的图片全部导出到本地目录，返回保存路径列表。""" doc = Document(path) Path(out_dir).mkdir(parents=True, exist_ok=True) saved = [] for i, rel in enumerate(doc.part.rels.values()): if "image" in rel.reltype: img_data = rel.target_part.blob ext = Path(rel.target_ref).suffix or ".png" file_name = f"image_{i:02d}{ext}" target = Path(out_dir) / file_name with open(target, "wb") as f: f.write(img_data) saved.append(str(target)) return saved逻辑说明：doc.part.rels 是正文部件关系表，reltype 中包含 image 的关系即图片资源；rel.target_part.blob 拿到的是图片的原始二进制字节；rel.target_ref 保存内部路径如 word/media/image1.png，据此判断扩展名。整个流程不引入 Pillow 等第三方图像库，图片文件直接落盘。
参数修改思路：想让图片文件名跟文档里出现的顺序对应，需要回到 body 的 XML 中查找 drawing 元素，按出现顺序关联 blip 的 rId；这套方案输出的是关系表顺序，对多数“把图捞出来做备份”的场景已经够用。
4.3 页眉页脚按节读取，避免首页不同漏数据
正文提取完了，别忘了页眉页脚。很多正式文档把公司名称、文档编号、版本号放在页眉里，如果只读正文，这些关键元数据就丢了。页眉页脚是分节管理的，Word 里每个节可以有独立的页眉页脚，还可能设置“首页不同”或“奇偶页不同”：
from docx import Document def extract_headers_footers(path: str) -> list[dict]: """按节提取页眉页脚文本。只取每个 section 的第一个页眉页脚示例。""" doc = Document(path) result = [] for sec in doc.sections: header_text = sec.header.paragraphs[0].text if sec.header.paragraphs else "" footer_text = sec.footer.paragraphs[0].text if sec.footer.paragraphs else "" result.append({"header": header_text, "footer": footer_text}) return result逻辑说明：doc.sections 返回文档的所有分节；每个 section 的 header 和 footer 都是独立部件，可能为空对象，所以先判断 paragraphs 列表是否为空。这个版本拿的是“该节默认页眉/页脚”。如果文档启用了首页不同，首页内容会存放在 first_page_header 属性里，需要单独读取。
参数修改思路：要覆盖首页和奇偶页，改成 sec.first_page_header.paragraphs 和 sec.even_page_header.paragraphs 逐个判断。页眉页脚里也常带图片或表格，想完整解析得复用 4.1 和 4.2 的思路对这些部件单独处理。
5. 解析 Word 文档常见问题排查：5 个避坑记录与处理清单
5.1 现象：Document() 直接抛 BadZipFile，文件打不开
现象：把文件路径传给 Document() 时抛出 zipfile.BadZipFile，提示文件不是压缩包。但文件明明是用 Word 另存出来的，扩展名也是 .docx。
原因：要么文件实际是旧版 .doc 二进制格式，只是改了后缀名；要么是某些协同办公软件导出的伪 docx，本质是 HTML 或 RTF 内容套了 docx 外壳。python-docx 只认真正的 ZIP 容器，所以打开即失败。
解决：先做格式嗅探，读取文件的开头几个字节判断真实类型：
def is_docx(path: str) -> bool: """读取文件头，判断是否为合法 docx（ZIP 容器以 PK 开头）。""" with open(path, "rb") as f: return f.read(4).startswith(b"PK") def safe_open_document(path: str): from docx import Document if not is_docx(path): raise ValueError(f"文件不是合法 docx: {path}") return Document(path)逻辑说明：合法 ZIP 文件头固定是 PK 两个 ASCII 字符，0x50 0x4B。is_docx 只读前 4 字节，开销极小。safe_open_document 在打开前先验证，把错误提前到可解释的阶段。
5.2 现象：表格读出来列数暴增，一行出现多个重复值
现象：Word 里看到一个 3 列的表格，解析后同一行却输出 5 个单元格，其中两列内容一模一样。
原因：横向合并单元格时，Word 内部会让被合并的单元格在 gridSpan 中占据多个网格位置。row.cells 按网格返回对象，于是同一个合并单元格被返回多次。
解决：按 id() 去重是第一步，但去重后会丢失“这个单元格跨了几列”的信息。如果需要精确还原，必须读取 tc 节点的 gridSpan 属性：
from docx.oxml.ns import qn def row_grid_spans(row) -> list[int]: """返回一行中每个单元格实际占用的列宽数 gridSpan。""" spans = [] for tc in row._tr.tc_lst: tc_pr = tc.tcPr grid_span = 1 if tc_pr is not None and tc_pr.gridSpan is not None: grid_span = tc_pr.gridSpan.val spans.append(grid_span) return spans逻辑说明：row._tr 是行对应的 XML 节点，tc_lst 返回该行真正的单元格元素，不和合并视图混淆；gridSpan 表示当前单元格跨几列。输出 spans 后，你可以自己决定是去重还是按跨列数补齐位置。
提示：如果业务只关心“提取内容不关心布局”，id() 去重足够；如果还要还原表格视觉结构，gridSpan 是必须引入的参数。
5.3 现象：同一段文字读出来被拆成好几条，顺序看起来是乱的
现象：一段完整的中文介绍，用 doc.paragraphs 读取后发现文字被切成多个短段落，或是同一段落内部出现乱序。
原因：Word 的段落不是按“句子”存储，而是按 run 存储。用户每次修改格式、输入法切换、修订记录，都可能生成新的 run。python-docx 暴露的是这些底层 run，p.text 已经帮你做了拼接，但如果代码里直接遍历 p.runs 再各自入库，就会看到碎片化现象；某些特殊字符域（如交叉引用）还会让 run 在 XML 中的存放位置与视觉顺序不一致。
解决：除非要做精细的格式判断，否则一律用 p.text 拿文本，不要自己拼 run。确需按 run 处理时，先按 p.text 切分逻辑完整性，再把 run 级属性做合并：
for p in doc.paragraphs: # 正确：用 p.text 拿完整段落 full_text = p.text # 谨慎：只有需要逐字符格式时才遍历 runs merged = "".join(r.text for r in p.runs)逻辑说明：single source of truth 是 p.text。runs 遍历只用于获取“某一段落里有没有加粗”“字体颜色是什么”这类元信息，不能用它重建正文，否则早晚会遇到 run 拆分导致的内容串位。
5.4 现象：Word 里能看到文本框内容，导出的纯文本里却没有
现象：文档页面上有醒目的橙色提示框，里面是重要提示文字，但 extract_text() 的结果里完全找不到这段内容。
原因：文本框在 Word 内部属于 DrawingML 图形对象，内容是嵌套在 w:txbxContent 节点里的文字。python-docx 的 doc.paragraphs 和 doc.tables 都不会包含这些包装在图形内的文本，所以常规遍历全部漏掉。
解决：在正文 XML 里定向搜索 txbxContent 节点并收集其中的 w:t 文本节点：
from docx import Document from docx.oxml.ns import qn def extract_textbox_text(path: str) -> list[str]: """提取 docx 中所有文本框内的文字。""" doc = Document(path) texts = [] for el in doc.element.body.iter(qn("w:txbxContent")): text = "".join(node.text or "" for node in el.iter(qn("w:t"))) if text.strip(): texts.append(text.strip()) return texts逻辑说明：iter 方法遍历整个 XML 子树，找到所有名为 txbxContent 的节点；在这个节点内部再找所有 w:t 节点，把它们的文本值拼接。w:t 是 Word 文本的最小存储单元，文本框内容也用它承载。注意这个方法拿不到形状位置信息，但能解决“内容缺失”的核心问题。
参数修改思路：公式和 SmartArt 是另一个坑，它们不一定以 w:t 形式存在。公式可能走 OMML 数学命名空间，SmartArt 数据在单独 diagram 部件里。如果业务必须解析这两类内容，建议评估投入产出比——很多时候把“解析不到”做成提示项，比强行解析更务实。
5.5 现象：几十 MB 的文档一跑就卡，内存涨得可怕
现象：解析一个带几十张高清图的 docx，脚本运行几秒后内存占用飙升，甚至直接卡死。
原因：Document(path) 在构造阶段会把 docx 包内的解析结果全部载入内存，包括所有图片的二进制数据。大文档的媒体资源可能占几十 MB 甚至上百 MB，全部加载自然吃力。
解决：按需读取。用 zipfile 直接从包里取对应部件，而不是让解析库一次性把整个文档拽到内存：
import zipfile import xml.etree.ElementTree as ET def load_body_xml_only(path: str) -> bytes: """只读取 word/document.xml，不加载图片等媒体资源。""" with zipfile.ZipFile(path) as z: return z.read("word/document.xml")逻辑说明：zipfile 可以精确读取包内某一个成员。只取 document.xml 后，XML 原始字节占用通常在几 MB 到十几 MB，远小于整包体积。这样做的代价是失去了 python-docx 的对象封装，所以这条方案只适合“文本为主、图片巨大、内存受限”的极端场景。一般任务不需要，但你需要知道这根救命绳在哪。
参数修改思路：如果只是避免图片进内存，也可以把 4.2 节的 extract_images 放在 Document 打开之前执行，用 zipfile 把图片先抽走，再打开一个“瘦身”后的副本。这样既保留解析对象的便利，又绕开了大图片的内存噪声。
6. 进阶技巧：把解析函数拼成入库流水线，用一次脚本验证全流程
当你手头有多个解析函数时，最忌逐个调用、手动拼接结果。我习惯把它们封装成一个入口函数，输出 JSON 文件，同时附带一个 MD5 指纹，用指纹比对验证“这次结果是不是和上次一致”。这个习惯在做批量入库时特别有用，它可以自动发现“同一份文档解析结果突然变了”的异常情况。
import hashlib import json from docx import Document def docx_to_json(path: str) -> dict: """把整份 docx 解析成结构化字典，供入库程序直接消费。""" doc = Document(path) return { "text": extract_text(path), "paragraphs": extract_paragraphs_with_style(path), "tables": extract_tables(path), "images": extract_images(path), } def save_with_hash(data: dict, out_path: str) -> str: """输出 JSON 文件并返回其 MD5 指纹。""" payload = json.dumps(data, ensure_ascii=False, indent=2) digest = hashlib.md5(payload.encode("utf-8")).hexdigest() with open(out_path, "w", encoding="utf-8") as f: f.write(payload) return digest调用方式和验证流程：
python -c "import docx_to_json; digest=docx_to_json.save_with_hash(docx_to_json.docx_to_json('sample.docx'), 'out.json'); print(digest)"第一次运行后记录指纹，之后每次批量重跑都对比输出指纹。指纹变了的文件，要么文档本身被改过，要么解析代码有回归，这两种情况都需要人工检查。这个验证思路成本极低，却能把“无法确认解析是否正常”的黑匣子状态打破。
我做这类任务的最后一个个人习惯是：解析代码永远不要只写一个函数，而是拆成“结构检查、文本提取、表格提取、图片提取、结果组装”五个独立单元。每换一批文档，先跑结构检查确认文件类型正常，再跑文本提取看内容，最后才校验表格和图片。宁可多花三分钟分步调试，也不要在一个大函数里凭着感觉找问题。希望你也能把这套思路用在自己的 Word 解析任务上，少踩几个我踩过的坑。
本文还有配套的精品资源，点击获取
