Python 实现 Markdown 与 Word 文档互转

在日常开发与文档处理中，Markdown 与 Word 是两种定位截然不同的格式。Markdown 以纯文本为基础，结构轻量、便于版本管理，适合技术文档、笔记和静态站点内容；Word 则凭借成熟的排版能力和审阅功能，在企业环境与正式交付场景中依然不可替代。当同一份内容需要在两种场景间流转时，格式转换便成了一个绕不开的环节。

手动复制粘贴不仅效率低下，还容易丢失标题层级、列表结构和表格格式。借助 Python 文档处理库，可以将这一过程自动化。本文以 Spire.Doc for Python 为例，介绍 Markdown 与 Word（DOC/DOCX）互转的实现方式，并讨论转换中需要注意的实际问题。

环境准备

Spire.Doc for Python 通过 pip 即可安装，无需依赖本地安装的 Microsoft Word 或其他办公软件。

bash 复制代码

pip install Spire.Doc

在脚本中导入所需模块：

python 复制代码

from spire.doc import *
from spire.doc.common import *

该库从 12.6.0 版本开始支持 Markdown 文档的加载与保存。如果使用较早版本，Markdown 相关功能可能不可用。

Markdown 转 Word

将 Markdown 转换为 Word 的核心逻辑只有两步：加载源文件时指定格式为 FileFormat.Markdown，保存时指定目标格式为 FileFormat.Docx 或 FileFormat.Doc。

python 复制代码

from spire.doc import *
from spire.doc.common import *

document = Document()
document.LoadFromFile("input.md", FileFormat.Markdown)

# 输出为 DOCX
document.SaveToFile("output.docx", FileFormat.Docx)

# 如需旧版 DOC 格式
# document.SaveToFile("output.doc", FileFormat.Doc)

document.Close()

代码中 LoadFromFile 的第二个参数显式声明了源文件格式。虽然对于 .md 后缀，库也能自动识别，但显式指定可以避免歧义。转换后的 Word 文档会保留 Markdown 中的标题层级、列表、表格等基础结构，但 Word 的复杂排版能力（如页眉页脚、多栏布局）在 Markdown 中本就不存在，因此输出结果以内容结构清晰为主，而非精细排版。

Word 转 Markdown

反向转换的代码结构完全对称。加载 Word 文件时无需额外指定格式（.doc 和 .docx 均可自动识别），保存时使用 FileFormat.Markdown。

python 复制代码

document = Document()
document.LoadFromFile("input.docx")

document.SaveToFile("output.md", FileFormat.Markdown)
document.Close()

Word 中的各级标题会映射为 Markdown 的 # 到 ###### 标签，段落保留换行，有序与无序列表被正确识别，表格也会转换为 Markdown 表格语法。对于以文字内容为主的文档，这一转换过程基本可以保留核心信息。

图片处理：一个容易被忽视的问题

Word 转 Markdown 时，图片的处理方式值得特别留意。默认情况下，Spire.Doc 会将文档中嵌入的图片以 Base64 编码形式直接写入 Markdown 文件。这种做法的优点是单文件自包含，分享时不会丢失图片；但缺点同样明显：当文档包含多张高清图片时，生成的 .md 文件体积会急剧膨胀，可能达到数十甚至上百 MB，导致编辑器卡顿，也不利于放入 Git 等版本控制系统。

一种可行的缓解方式是在转换前先提取图片到独立目录，再以相对路径引用的方式写入 Markdown。该库提供了 document.Images 集合用于遍历图片数据。不过需要注意的是，SaveToFile 方法本身并不提供"保存时自动外链图片"的参数，提取后仍需对生成的 Markdown 内容做后处理，将 Base64 图片块替换为 ![](images/img_x.png) 形式的引用。如果转换任务频繁且图片较多，建议将这一步骤纳入脚本流程，而非依赖手动操作。

另一种更简单的策略是在转换前移除图片。如果 Markdown 产物主要用于文本检索或语料准备，图片并非必需，跳过图片可以显著减小文件体积并提升转换速度。

实际转换中的局限与应对

格式转换并非无损。Markdown 的语法表达能力有限，Word 中的若干元素在转换后可能丢失或降级：

文本框与多栏排版：Markdown 没有对应语法，通常降级为普通段落或直接丢失。
复杂表格样式：边框、底纹、单元格合并等格式在 Markdown 表格中无法保留，仅保留行列结构。
页眉页脚与页码：Markdown 作为纯文本格式不包含页面概念，这些元素不会被输出。

因此，在批量转换之前，建议先用一份有代表性的文档做试转换，确认关键内容（标题层级、代码块、表格数据）的保留情况。由于输出是纯文本，也可以编写简单的校验脚本，检查文件是否为空、标题层级是否正确、关键段落是否存在，这比逐个人工核对更为可靠。

对于需要批量处理的场景，将单文件转换逻辑封装为函数后，配合 os.listdir 遍历目录即可：

python 复制代码

import os

input_folder = "docs"
output_folder = "markdown_output"

for filename in os.listdir(input_folder):
    if filename.lower().endswith(".docx"):
        doc = Document()
        doc.LoadFromFile(os.path.join(input_folder, filename))
        md_name = os.path.splitext(filename)[0] + ".md"
        doc.SaveToFile(os.path.join(output_folder, md_name), FileFormat.Markdown)
        doc.Close()

在 Windows 环境下，如果目标目录中的文档曾被 Word 打开过，可能会产生以 ~$ 开头的临时文件，遍历时需要注意过滤。

适用场景与选择建议

Markdown 转 Word 的典型场景包括：用 Markdown 完成内容撰写后，需要以正式格式交付给非技术同事或客户；将静态站点中的文档导出为可打印的 Word 版本。反过来，Word 转 Markdown 则常见于存量文档迁移------将历史 Word 手册批量转为 Markdown 后接入文档站点或知识库，或者为文本检索、大模型语料准备纯文本数据。

需要明确的是，这类转换工具提供的能力侧重于内容结构的迁移，而非版式的精确复刻。如果需求是保留 Word 文档的每一处排版细节并输出 PDF，那属于另一类任务（该库也支持 Word 转 PDF），与 Markdown 互转的目标并不相同。理解这一点，有助于在合适的场景中使用合适的工具，避免对转换结果产生不切实际的预期。