告别 python-docx：用纯 Python 标准库实现的一个 Word 转 Markdown 的工具-超好用(附源码）

前言在日常工作中我们经常需要将 Word 文档转成 Markdown——比如把技术文档发布到博客或者把论文转成纯文本方便版本管理。市面上现有的方案通常依赖python-docx、pandoc或mammoth等第三方库要么安装链条长要么转换结果不够理想丢标题层级、编号乱掉、图片丢失……。我想做一件事仅用 Python 标准库xml.etree.ElementTreezipfile直接拆 .docx 的 XML精准还原 Word 文档的结构到 Markdown。感恩AI加持快速实现了docx2md—— 一个零转换依赖、支持命令行与 Web 双界面的 Word 转 Markdown 工具。这篇文章记录整个实现过程。在线体验点击立即体验 DocX 转 Markdown (在线体验的前端是另外工程维护为最新代码本文完成后界面可能有更新项目已开源欢迎试用、反馈、点赞、关注源码地址GitHub - doc2md转换前端界面如下一、.docx 文件到底是什么很多人以为.docx是一个二进制文件其实不是——它本质上就是一个ZIP 压缩包里面装着一堆 XML 文件。把任意.docx文件重命名为.zip解压后你会看到这样的结构document.docx (ZIP) ├── [Content_Types].xml ├── word/ │ ├── document.xml ← 文档正文段落、表格、图片引用 │ ├── styles.xml ← 样式定义标题级别、字体、段落格式 │ ├── numbering.xml ← 编号定义自动编号格式、起始值 │ ├── _rels/ │ │ └── document.xml.rels ← 资源关系表图片路径、超链接目标 │ └── media/ │ ├── image1.png ← 嵌入的图片 │ └── image2.jpg └── ...核心思路就清晰了用zipfile打开压缩包用xml.etree.ElementTree解析 XML逐个元素翻译成 Markdown。importzipfileimportxml.etree.ElementTreeasETwithzipfile.ZipFile(document.docx)aszf:doc_xmlzf.read(word/document.xml)rootET.fromstring(doc_xml)# 接下来遍历 XML 元素...听起来简单但真正的挑战在于 Word XML 的复杂度——尤其是标题层级、自动编号和样式继承。二、核心挑战标题层级怎么判断放弃 “按名字匹配”最容易想到的思路是匹配样式名称——如果段落的样式叫 “Heading 1” 就算一级标题。但这个方案很脆弱用户完全可以把 “Heading 1” 改名为 “我的大标题”匹配就失效了。正解outlineLvl 属性Word 内部判断标题层级靠的并不是样式名称而是一个叫outlineLvl大纲级别的 XML 属性。这个属性存储在styles.xml中w:stylew:typeparagraphw:styleIdHeading1w:pPrw:outlineLvlw:val0/!-- 0 H1, 1 H2, ... --/w:pPr/w:style不管用户怎么改样式名outlineLvl的值不会变。我的实现就是读这个属性来判断标题级别outlineLvl 0→# H1outlineLvl 1→## H2outlineLvl 5→###### H6outlineLvl ≥ 6或无此属性 → 正文段落样式继承链Word 的样式支持继承basedOn比如 “Heading 2” 可能继承自 “Heading 1”而 “Heading 1” 又继承自 “Normal”。要正确拿到outlineLvl必须沿着继承链向上追溯def_resolve_outline_level(self,style_id):visitedset()whilestyle_idandstyle_idnotinvisited:visited.add(style_id)styleself._styles.get(style_id)ifstyleandstyle.get(outlineLvl)isnotNone:returnstyle[outlineLvl]style_idstyle.get(basedOn)ifstyleelseNonereturnNone用visited集合防止循环继承导致无限递归——虽然正常文档不会有这种情况但做防御性处理总没坏处。三、最复杂的部分自动编号如果说标题层级是有点麻烦那自动编号就是真正的Hard模式。Word 的编号系统涉及三层 XML 结构加上格式模板、计数器状态管理、Legal 编号模式……这是整个项目最复杂的模块。编号系统架构Word 的编号由三层结构组成numbering.xml ├── abstractNum (抽象编号定义) │ ├── lvl ilvl0: numFmtchineseCounting, lvlText第%1章 │ ├── lvl ilvl1: numFmtdecimal, lvlText%1.%2 │ └── lvl ilvl2: numFmtdecimal, lvlText%1.%2.%3 │ ├── num numId1 → abstractNumId0 (具体编号实例) │ └── 可选 lvlOverride (覆盖某些层级的格式或起始值) │ └── 段落通过 numPr 引用 w:numPr w:numId w:val1/ w:ilvl w:val0/ /w:numPrabstractNum定义编号的模板——每个层级用什么格式中文、罗马数字、阿拉伯数字文本模板是什么第%1章、%1.%2.%3num是具体的编号实例指向某个 abstractNum并且可以覆盖部分设置段落通过numPr引用 numId ilvl层级格式模板展开编号的文本模板类似于printf格式化。比如第%1章中的%1表示第 1 层级的当前计数值。%1.%2.%3表示用点号连接三个层级的计数。def_format_level_text(self,lvl_text,ilvl,counters,levels_info):resultlvl_textforiinrange(ilvl1):placeholderf%{i1}ifplaceholderinresult:counter_valcounters.get(i,1)formattedself._format_number(counter_val,fmt)resultresult.replace(placeholder,formatted)returnresult其中_format_number()需要支持多种编号格式numFmt 值输出示例decimal1, 2, 3chineseCounting/koreanDigital2一, 二, 三upperRomanI, II, IIIlowerLettera, b, cbullet• (无序列表)计数器管理编号计数的核心逻辑当父级别递增时所有子级别的计数器必须重置。第一章 (ilvl0, counter1) 1.1 (ilvl1, counter1) 1.2 (ilvl1, counter2) 第二章 (ilvl0, counter2) 2.1 (ilvl1, counter1) ← 自动重置 2.2 (ilvl1, counter2)这个逻辑在代码中的实现是当某个 ilvl 的计数器递增时清除所有 ilvl 的计数器条目。Legal 编号模式isLglWord 有一个不太常见但很重要的功能叫 Legal Numbering。启用时上级层级的占位符会强制转为阿拉伯数字而当前层级保持自己的格式。比如章节标题用中文“第一章”但小节编号中引用章节号时变成阿拉伯数字“1.1” 而不是 “一.1”。这个细节的正确处理让文档转换出来的编号更接近 Word 原始显示效果。四、其他内容元素的处理表格Word 的表格是w:tbl→w:tr→w:tc的嵌套结构。转换策略| 列1 | 列2 | 列3 | |-----|-----|-----| | 数据 | 数据 | 数据 |关键细节单元格内的|字符必须转义为\|否则会破坏 Markdown 表格结构单元格内的多段落换行提供两种模式用空格合并兼容性好或用br保留结构清晰图片图片的提取链条比较长document.xml 中的 w:drawing → 找到 a:blip r:embedrId5 → 查 document.xml.rels 得到 rId5 → media/image1.png → 从 ZIP 中读取 word/media/image1.png → 保存到输出目录 images/image_001.png一个有趣的细节Word 有时会在图片的 alt text 中插入 AI 生成的描述附带免责声明“AI 生成的内容可能不正确”代码中会自动清理这类文本。超链接超链接也依赖document.xml.rels关系表。段落中的w:hyperlink r:idrId7对应到关系表中的外部 URL最终转为[链接文字](https://example.com)格式。内联格式XML 属性Markdownw:b/**加粗**w:i/*斜体*w:b/w:i/***粗斜体***w:strike/~~删除线~~等宽字体 (Consolas 等)代码需要注意的是Word 中属性的开关写法w:b/表示开启加粗而w:b w:val0/表示显式关闭加粗——不能简单地看标签是否存在。五、封面、目录与摘要的智能处理学术论文场景下通常希望在转 Markdown 时去掉封面页和目录页。这需要在 XML 层面准确识别它们。封面检测封面页的终止标志是第一个分页符——Word 会在封面和正文之间插入强制分页w:brw:typepage/!-- 或节分页 --w:sectPrw:typew:valnextPage//w:sectPr找到第一个分页符的位置之前的全部内容就是封面。目录检测三重策略目录在 Word XML 中可能以三种形式出现代码用三种策略逐一检查SDT结构化文档标签w:sdt中包含w:docPartGallery w:valTable of Contents/段落样式样式 ID 匹配TOC1–TOC9、TOCHeading等域代码w:instrText中包含TOC关键字摘要保留在before_toc_keep_abstract模式下虽然会删除目录之前的所有内容但会智能保留摘要和Abstract对应的段落。识别方式是扫描标题文本中包含 “摘要” 或 “Abstract” 关键词的段落及其后续正文内容。四种目录处理模式模式效果none保留所有内容toc_only只移除目录条目before_toc移除目录及其之前的全部内容before_toc_keep_abstract移除目录及之前内容但保留摘要六、Web 界面实现除了命令行工具我还用 Flask 做了一个 Web 界面方便不熟悉命令行的用户使用。整体架构浏览器 (index.html) ├─ 拖拽/选择文件上传 ├─ 设置转换选项 ├─ POST /convert → 后端转换 ├─ 接收 JSON 结果 → 渲染预览 └─ GET /download/id → 下载文件后端只有 5 个核心路由路由功能GET /渲染上传页面POST /convert接收文件、转换、返回预览 JSONGET /download/id下载 .md 或 .zipGET /files/id/path提供图片资源服务GET /health健康检查前端页面展示前端是一个单页应用所有功能集中在一个 HTML 文件中使用原生 JavaScript无框架依赖。上传区域拖拽或点击上传.docx文件支持多文件批量上传。上传后显示文件列表包含文件名、大小信息和删除按钮。转换选项选择文件后会展开选项面板✅ 提取嵌入图片✅ 去掉第一页封面 目录处理模式4 种可选 表格单元格换行方式空格 /br转换与预览点击开始转换后页面显示进度条。转换完成后自动切换到预览区域提供两种视图源码视图显示原始 Markdown 文本深色背景代码风格渲染预览使用marked.js将 Markdown 渲染为 HTML直接在页面内预览效果多文件时顶部会出现 Tab 标签页切换。下载与复制预览区域底部提供一键复制Markdown 源码到剪贴板⬇️智能下载单文件无图片 → 直接下载.md有图片或多文件 → 打包为.zip前端关键技术细节图片路径重写预览时Markdown 中的相对图片路径如images/image_001.png需要重写为服务器的资源路由/files/{result_id}/{filename}/images/image_001.png这样图片才能在浏览器中正确显示。文件清理后端维护一个内存字典存储转换结果后台线程每 60 秒检查一次自动清理超过 10 分钟的结果和临时文件避免磁盘占用累积。七、项目结构最终的项目结构非常精简doc2md/ ├── pyproject.toml # 项目配置 依赖声明 ├── requirements.txt # pip 依赖仅 Flask ├── README.md ├── templates/ │ └── index.html # Web 前端~700 行单文件 SPA └── converter/ ├── __init__.py # 包元信息 ├── cli.py # CLI 入口argparse ├── webapp.py # Flask Web 服务~500 行 ├── word2md.py # 核心转换引擎~850 行 └── numbering.py # 编号与大纲解析~550 行整个转换核心不到 1500 行代码加上 Web 服务和 CLI 也不到 2500 行。唯一的第三方依赖是 Flask用于 Web 界面Word 转换本身完全基于标准库。八、使用效果命令行# 单文件doc2md paper.docx-opaper.md# 论文场景去封面、去目录、保留摘要doc2md paper.docx --skip-cover --toc-mode before_toc_keep_abstract# 批量转换doc2md *.docxWeb 界面python-mconverter.webapp# 浏览器打开 http://localhost:5000总结这个项目最大的收获是深入理解了 Word 的 XML 结构。.docx看似复杂但每个功能标题、编号、图片、表格都有明确的 XML 属性与之对应。只要找对了属性转换逻辑就会非常精准——比依赖文本匹配或正则猜测可靠得多。关键设计决策回顾✅ 用outlineLvl而非样式名称判断标题 → 对用户自定义样式零敏感✅ 直接解析 XML 而非依赖第三方库 → 零转换依赖、可控性强✅ 多级编号共享计数器 子级自动重置 → 精确还原 Word 编号行为✅ 前后端分离的预览机制 → 转换 预览一步到位项目已开源欢迎试用和反馈GitHub - doc2md