简介：这是一款使用Go语言开发的Word文档转换工具，可将docx文件快速转为Markdown，适合需要批量整理文档、用Markdown写作或维护知识库的开发者。工具提供简洁的命令行用法，支持标题、超链接、缩进、表格、清单、加粗、斜体、删除线与嵌入图片等常见Word样式，覆盖多数日常转换需求。压缩包仅71KB，共11个文件，包括Go源码、测试文件、Makefile构建脚本、Go模块定义、GitHub Actions工作流yml、README说明及项目截图，结构清晰，方便直接编译或阅读源码。目前已有2720人学习使用，适合想提升文档处理效率的工程师、技术博主及需要将旧Word资料迁移到Markdown体系的用户使用。通过该资源可获得完整可运行的项目源码与测试用例，既能作为命令行工具直接使用，也可参考其实现思路嵌入到自己的文档工具链中。 把 Microsoft Word 文档转成 Markdown，在很多人看来无非是复制粘贴再调一下格式。但真正做内容的同学都清楚，Word 里一个看似规整的标题，粘到 Markdown 编辑器之后可能变成一团乱麻；表格只要跨过页，复制出来就缺行少列；更不用说图片、批注、修订痕迹这些“附加品”带来的干扰。我今天要聊的 docx2md，就是为了解决这一系列痛点而生的小工具，它专门负责把 .docx 格式的 Word 文档准确、整洁地转换成 Markdown 文本。
这个工具适合三类人：一是长期用 Markdown 写文档、但经常收到 Word 版资料的内容从业者；二是需要在博客、知识库或 AI 工作流里统一数据格式的开发者；三是被 Word 排版折腾到崩溃、想彻底迁移到 Markdown 写作体系的普通用户。如果你也正在经历 Word 和 Markdown 之间的格式鸿沟，下面这些从原理到实战的拆解，应该能帮你少走不少弯路。
1. 为什么需要 docx2md：项目背景与核心价值
1.1 文档工作流中的“最后一公里”
先说一个非常常见的场景：你在团队里负责技术方案或产品文档，同事用 Microsoft Word 写好了初稿，里面带着封面、目录、各级标题、表格、截图，甚至还有批注。你拿过来之后，想把它整理进公司的知识库或者个人博客，而知识库和博客底层都是 Markdown。这时你面临的问题不是“要不要转”，而是“怎么转得体面”。
直接复制粘贴最省事，但后果通常很具体：标题层级丢失、列表缩进错乱、表格变成纯文本、图片一张也带不出来。更麻烦的是，Word 里的“样式”和 Markdown 里的“语法”是两套完全不兼容的逻辑，Word 用样式表来表达“这是一级标题”，Markdown 用#来表达，中间必须有一个解析层。docx2md 就是补上这个解析层的工具。
从我自己的使用体验来看，它的核心价值不在于“能转”，而在于“转完之后格式不用再大改”。一份百页左右的项目文档，手工整理至少要一两个小时，而自动化转换加上少量人工校对，十分钟内就能完成。省下来的时间，才是工具能把人从重复劳动里解放出来的真正意义。
1.2 选型思路：自研解析还是直接上 pandoc
聊到 Word 转 Markdown，很多人第一个想到的是 pandoc。pandoc 确实强大，支持格式极多，命令行一条指令就能完成转换。那为什么还要自己维护一个 docx2md 这样的工具？我的理由有三点：
第一，pandoc 的默认输出是“通用型”的，它遵循 Markdown 标准，但不会替你照顾博客系统或者知识库的特殊需求。比如图片放在哪个目录、表格是否要带对齐标记、代码块要不要标准化成带语言标注的形式，这些都需要额外加工。第二，pandoc 的安装包体积不小，依赖也多，在一些受限环境里部署并不方便。第三，维护一个自己的工具，可以针对高频遇到的结构做定制解析，比如公司内部模板生成的 docx，里面标题样式命名是“标题 1”，正文样式是“正文文本”，这些规则只需写一次，后面就能长期复用。
所以说到底，pandoc 是“瑞士军刀”，docx2md 是“专门开锁的钥匙”。如果你只需要一次性转换，用 pandoc 完全没问题；如果你要长期在固定工作流里批量处理 Word 文档，有一套定制化工具会更顺手。
| 对比项 | pandoc | docx2md |
|---|---|---|
| 安装依赖 | 较重，需单独安装 | 轻量，Python 环境即可 |
| 定制能力 | 需 filter 和模板，门槛高 | 代码逻辑直接可控 |
| 图片处理 | 输出相对通用 | 可按项目需求定义路径与命名 |
| 批处理效率 | 单文件为主 | 便于改造为批量流程 |
2. docx2md 核心设计：从 docx 到 Markdown 的转换原理
2.1 docx 的真实结构：藏在 zip 里的 XML
很多人以为 .docx 是一个“文档文件”，其实它本质是一个压缩包，里面装着一堆 XML 文件。你可以把扩展名改成 .zip 解压看看，核心内容是word/document.xml，文档里的段落、表格、文字、样式信息全部以 XML 节点形式存放在里面。
这意味着，如果我们要把 Word 文档转成 Markdown，最底层的思路不是“读文字”，而是“解析 XML”。比如一个段落，在 XML 中对应<w:p>节点，段落里的文字又分成多个<w:r>（run）节点，字体、加粗、斜体这些属性都挂在 run 级别的属性里。标题、正文、列表这些语义，则通过<w:pStyle>指向文档中定义的样式名称来识别。
在 Python 生态里，python-docx帮我们封装了这些 XML 细节，可以直接用对象来操作段落和表格，省去手动爬 XML 的大量工序。一个最简单的读取示例长这样：
from docx import Document doc = Document("input.docx") for para in doc.paragraphs: print(para.style.name, "|", para.text)遍历doc.paragraphs就能拿到所有段落，para.style.name告诉我们这段用的什么样式，para.text是纯文本内容。转换工具的起点就在这里：把 Word 的样式名映射成 Markdown 语法符号，比如样式名包含“标题 1”就输出#，包含“标题 2”就输出##。
2.2 转换管线的四个阶段
在实际实现 docx2md 时，我不会只写一个“遍历段落然后拼接字符串”的简单脚本，而会把它设计成四条清晰的阶段，方便逐步排查问题。
第一阶段是读取与归一化。通过 python-docx 加载文档，把所有段落、表格、图片的关系梳理出来。第二阶段是内容分类。把每个段落标记出类型：普通正文、标题、列表、引用、代码块、分割线等，这个分类规则是整个转换质量的基石。第三阶段是逐块转换。标题变成对应层级的#，正文直接输出，列表项按层级补空格，表格按行和列拼成 Markdown 表格语法。第四阶段是后处理，包括清理多余空行、处理特殊字符（比如把全角空格转成常规空格）、检查图片是否成功导出。
把转换过程拆成阶段的好处是，一旦转换结果出问题，你可以很快定位是在哪一步出的错。比如表格全部乱了，先看第二阶段分类对不对；如果标题全变成了正文，就看第三步的样式映射表有没有生效。这种“管线化”的设计思路，放到其他格式转换项目里也一样适用。
3. 实操：快速把 docx2md 跑起来
3.1 安装与基础命令
以我维护的 docx2md 工具为例，安装只需要一条命令：
pip install docx2md装好之后，最简单的转换命令是：
docx2md input.docx默认情况下，工具会在当前目录生成一个input.md文件。如果你希望指定输出文件名和图片保存的文件夹，可以用-o和--asset-dir参数：
docx2md input.docx -o output.md --asset-dir ./assets这个命令会把文档里所有图片导出到assets目录，同时在 Markdown 中生成对应的引用。我在一开始设计这个参数时，考虑的是博客写作场景——图片集中在一个文件夹里，推送 Git 仓库时不用在多个目录之间翻找。
3.2 表格、图片、链接等复杂元素怎么处理
Word 转 Markdown，最让人头疼的不是文字，而是表格和图片。
表格方面，docx2md 先把 docx 里的<w:tbl>节点解析成二维数组，然后逐行输出 Markdown 表格语法。第一行默认作为表头，第二行生成分隔线。列宽信息无法在 Markdown 中体现，所以如果原文表格列宽差异很大，转换后会显得比较平均，这类问题我通常建议在转换后交给 Markdown 编辑器里的表格插件微调。
图片方面，需要处理两件事：一是从 docx 压缩包中解压出真实图片文件，二是把文档里的图片引用位点替换成 Markdown 图片语法。docx 内部图片保存在word/media/目录，图片与文档位置的对应关系记录在word/_rels/document.xml.rels中，也就是通过rId进行的关联。工具要做的是遍历文档里的<w:drawing>节点，拿到对应的rId，再解析rels文件找到真实图片路径，最后把图片复制到指定的资产目录。
链接和代码块则相对简单。链接直接提取地址和显示文字，输出[文字](地址)格式即可。代码块主要靠识别 Word 中的代码样式（比如“HTML 代码”样式）或者通过手动标记识别，然后加上三个反引号包裹。
3.3 写一个批量转换脚本
单文件转换只是基础功能。在实际项目里，更多人需要的是批量处理。比如你接手了一个旧项目，里面有几百份 Word 文档要统一导入博客系统，这时候就需要写批量脚本。
import argparse from pathlib import Path from docx2md import convert def batch_convert(input_dir: Path, output_dir: Path): for docx_file in input_dir.glob("*.docx"): output_md = output_dir / f"{docx_file.stem}.md" convert(str(docx_file), str(output_md)) print(f"converted: {docx_file.name}") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--input_dir", type=Path, required=True) parser.add_argument("--output_dir", type=Path, required=True) args = parser.parse_args() args.output_dir.mkdir(parents=True, exist_ok=True) batch_convert(args.input_dir, args.output_dir)这个脚本简单直接：遍历输入目录下的所有.docx文件，逐个调用convert函数生成对应的 Markdown，再打印一条进度信息。我在跑大批量转换时，会再加上一个失败计数和异常堆栈输出，方便把转换失败的文件单独挑出来排查。
4. 常见问题与排查技巧实录
4.1 表格渲染错位怎么办
使用过程中反馈最多的问题，就是转换后的表格用 Typora 或 VSCode 预览时错位。大部分情况下，问题不是出在 Markdown 语法上，而是表格的单元格里混入了换行符。Word 表格中一个单元格可能有多个段落，直接拼接成一行会破坏表格结构。
我的处理方案是：读取单元格时，把内部的回车替换成<br>标签，这样既能保留换行语义，又不会破坏 Markdown 表格的行列结构。另外，如果表格里有合并单元格，Markdown 原生语法并不支持，目前的工具会按照“占位重复”的方式处理，也就是合并的区域会在每个相关行重复一次内容，虽然不完全还原视觉样式，但至少信息不丢失。
4.2 图片导出乱序和路径错乱
图片导出看起来简单，痛点在于“顺序”。Word 文档中图片的排列顺序和rels文件中的记录顺序可能不完全一致，如果工具只按 rId 顺序导出图片，生成的 Markdown 里图片顺序和原文就会对不上。
我踩过这个坑之后，现在实现的时候会先遍历全文，记录每个图片出现的先后顺序，再按这个顺序去rels中匹配图片文件，而不是直接遍历rels。另一个常见问题是文件名冲突，建议导出时统一加上编号前缀，比如img_0001.png。这样即使原文档里的图片名字相同，导出后也不会互相覆盖。
4.3 公式转换：OMML 到 LaTeX 的坑
Word 里用内置公式编辑器写的公式，在 docx 内部是以 OMML 格式存的，而 Markdown 生态主要支持 LaTeX 语法。这是一个比较深的坑，因为 OMML 和 LaTeX 的语法差异非常大，简单替换根本行不通。
目前 docx2md 的做法是内置一个 OMML 到 LaTeX 的映射规则，覆盖常见的分式、上下标、根号、求和符号等基础情况。复杂的矩阵、多行公式仍然可能出现转换不理想的情况。- my recommendation：遇到特别复杂的公式，我会在转换后手动检查，必要时直接在 Markdown 里手写 LaTeX 公式。数学公式本身是高度专业的排版内容，完全自动化在现阶段不现实。
4.4 编码与特殊字符问题
Word 文档里的字符远比 Markdown 复杂。全角空格、不间断空格、中文引号、特殊破折号，这些在 Word 中显示正常，但转换后可能会在 Markdown 渲染器里显示异常，甚至让代码块提前结束。
我的排查习惯是：转换后先用一个脚本检查特殊字符，重点关注\u00a0（不间断空格）和\u3000（全角空格），把它们统一替换成普通空格。中文引号和英文引号建议保留原样，因为不同渲染器的处理逻辑不同，强行转换有时会丢失语义。
| 常见问题 | 可能原因 | 解决办法 |
|---|---|---|
| 表格错位 | 单元格内含换行 | 转成<br>标签 |
| 图片顺序错乱 | rId 与文档顺序不一致 | 按文档遍历顺序匹配 |
| 公式乱掉 | OMML 与 LaTeX 语法差异 | 内置映射 + 手动复核 |
| 特殊字符异常 | 全角/不间断空格 | 后处理统一替换 |
| 图片名冲突 | 原文件重名 | 导出时加编号前缀 |
5. 把 docx2md 放进内容工作流
5.1 搭配 VSCode 与 Typora 高效使用
转出来的 Markdown 文件，最终是要给人看的，所以编辑器的选择也很关键。我自己日常用的是 VSCode，配合 Markdown Preview Enhanced 插件来预览。这个插件支持代码高亮、流程图和数学公式渲染，和 docx2md 转换出来的 Markdown 配合度很高。
Typora 则是另一个推荐选项，它胜在所见即所得，左侧写、右侧直接看到排版效果，对不熟悉 Markdown 语法的新手特别友好。把 docx2md 转换后的文件用 Typora 打开，可以快速检查表格有没有错位、图片路径是否正确、标题层级是否符合预期。这两款编辑器我都建议安装，VSCode 用于日常编辑和 Git 协作，Typora 用于最终校对。
5.2 对接博客、知识库与自动化流程
docx2md 更大的价值，在于能嵌入到自动化的内容流程里。比如你在 Coze 里搭建一个工作流：收到 Word 文档后，先通过 docx2md 转成 Markdown，再把 Markdown 内容交给大模型去做摘要或改写，最后格式化发布到博客。整个链路不需要人工在中间搬运格式，内容处理的效率会明显提高。
另外，如果你的博客是 Hugo 或 Hexo 这类静态网站生成器，docx2md 转出来的文件可以直接放到content目录下，文件名按惯例改成日期-标题.md即可发布。我曾经把一整本旧团队手册一次性转成 Markdown，导入知识库后，搜索、版本管理、多人协作都顺畅了很多。这件事真正做完之后我才意识到，格式统一带来的收益，比单个文档的排版精美要重要得多。
在团队里推 docx2md 一段时间之后，我最大的感触是：转换工具永远只是第一步，真正值得投入精力的是建立一套“Word 生产，Markdown 分发”的规范。让写文档的人继续用他们熟悉的 Word，让维护内容的人统一用 Markdown 处理，两边各干各擅长的事，中间由工具来衔接。如果让我重新做一遍这个项目，我会在一开始就把图片命名、合并单元格、特殊公式这些边界情况设计进整体框架，而不是等用户一个个反馈再去补丁式修复。工具本身不复杂，复杂的是你对自己内容流程的理解有多深。
本文还有配套的精品资源，点击获取
