Java 将 Word 文档转换为 Markdown：基础转换与导出选项详解

原创

用户12416476

发布于 2026-07-03 19:32:19

160

前言

在写技术文档、知识库内容或接口说明时，很多资料一开始都是 Word 格式，比如 .doc、.docx。但如果后续要放到 GitHub、Gitee、静态博客、文档站点或内部知识库中，Markdown 会更方便维护。

这篇文章记录一种在 Java 中把 Word 文档转换为 Markdown 的做法。内容分两部分：第一部分只做最基础的 Word 转 Markdown；第二部分再加入图片、列表、链接、表格、数学公式等导出设置。

一、准备工作

1. 开发环境

本文示例使用 Java 编写，建议准备以下环境：

JDK 8 或以上
Maven 项目
一个待转换的 Word 文件，例如：Data/toMarkdown.docx

示例中会用到 Spire.Doc for Java。它可以在 Java 程序中读取、转换和处理 Word 文档，不需要在服务器上安装 Microsoft Office。

2. Maven 依赖

在 pom.xml 中加入 Maven 仓库和依赖：

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.cn/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.7.0</version>
    </dependency>
</dependencies>

这里的版本号以 14.7.0 为例，实际项目中建议以官网或 Maven 仓库页面上的最新版本为准。

二、基础转换：Word 转 Markdown

先看最简单的情况：只需要把 .docx 文件转成 .md 文件，不处理额外的图片目录、链接格式或表格格式。

示例代码

import com.spire.doc.*;

public class WordToMarkdownBasic {
    public static void main(String[] args) {
        // 创建 Document 对象
        Document document = new Document();

        try {
            // 加载 Word 文档
            document.loadFromFile("Data/toMarkdown.docx");

            // 保存为 Markdown 文件
            document.saveToFile("toMarkdown_out.md", FileFormat.Markdown);
        } finally {
            // 释放资源
            document.close();
            document.dispose();
        }
    }
}

代码说明

这段代码的核心只有三步：

创建 Document 对象；
使用 loadFromFile() 读取 Word 文件；
使用 saveToFile() 并指定 FileFormat.Markdown 输出 Markdown 文件。

如果只是做普通的文档迁移，例如把说明文档、操作手册、接口文档从 Word 转为 Markdown，这种写法已经可以满足最基本的需求。

不过，Word 文档中经常会包含图片、表格、超链接、编号列表、数学公式等内容。直接转换虽然简单，但结果未必适合后续编辑，所以通常还需要配置一些 Markdown 导出选项。

三、高级设置：控制图片、列表、链接、表格和公式的导出方式

下面基于基础转换代码，增加一些常用的 Markdown 导出配置。

完整示例代码

import com.spire.doc.*;

public class WordToMarkdownWithOptions {
    public static void main(String[] args) {
        // 创建 Document 对象
        Document document = new Document();

        try {
            // 加载 Word 文档
            document.loadFromFile("Data/toMarkdown.docx");

            // 方式一：将图片直接转为 Base64 写入 Markdown
            // 适合不想单独管理图片文件的场景，但会导致 .md 文件体积变大
            // document.getMarkdownExportOptions().setImagesAsBase64(true);

            // 方式二：将 Word 中的图片提取到本地文件夹
            // 生成的 Markdown 会引用该目录下的图片
            document.getMarkdownExportOptions().setImagesFolder("D:\\Markdown\\Images");

            // 设置图片路径别名
            // 生成 Markdown 时，会使用该别名作为图片引用路径
            // document.getMarkdownExportOptions().setImagesFolderAlias("Images");

            // 设置列表导出方式
            // Plain_Text 表示将项目符号和编号列表按普通文本方式输出
            document.getMarkdownExportOptions().setListOutputMode(MarkdownListOutputMode.Plain_Text);

            // 保留 Word 中的下划线格式
            document.getMarkdownExportOptions().setSaveUnderlineFormatting(true);

            // 设置超链接输出方式
            // Reference 表示使用引用式链接，例如：[链接文字][1]
            document.getMarkdownExportOptions().setLinkOutputMode(MarkdownLinkOutputMode.Reference);

            // 设置 Office Math 数学公式输出方式
            // Math_ML 表示将公式输出为 MathML
            document.getMarkdownExportOptions().setOfficeMathOutputMode(MarkdownOfficeMathOutputMode.Math_ML);

            // 设置部分内容使用 HTML 语法保存
            // 这里表示表格使用 HTML 方式输出，适合复杂表格
            document.getMarkdownExportOptions().setSaveAsHtml(MarkdownSaveAsHtml.Tables);

            // 保存为 Markdown 文件
            document.saveToFile("toMarkdown_out.md", FileFormat.Markdown);
        } finally {
            // 释放资源
            document.close();
            document.dispose();
        }
    }
}

四、几个常用导出选项说明

1. 图片导出方式

Word 文档中如果包含图片，通常有两种处理方式。

第一种是将图片直接转成 Base64 写入 Markdown：

document.getMarkdownExportOptions().setImagesAsBase64(true);

这种方式的好处是 Markdown 文件本身就包含图片内容，移动文件时不容易丢图。缺点也很明显：生成的 .md 文件会变得很大，不太适合放到 Git 仓库长期维护。

第二种是把图片提取到指定文件夹：

document.getMarkdownExportOptions().setImagesFolder("D:\\Markdown\\Images");

这种方式更适合技术文档、博客文章和知识库。Markdown 文件只保存图片引用，图片文件单独放在一个目录中，后期维护会更清晰。

如果后续要把 Markdown 放到博客或文档站点中，可以再配合图片路径别名：

document.getMarkdownExportOptions().setImagesFolderAlias("Images");

这样生成的 Markdown 中，图片路径可以更接近实际发布目录。

2. 列表导出方式

Word 里的项目符号和编号列表，在转换成 Markdown 时可能会出现格式差异。如果希望列表不要使用 Markdown 的列表语法，而是按普通文本输出，可以设置：

document.getMarkdownExportOptions().setListOutputMode(MarkdownListOutputMode.Plain_Text);

这个选项适合一些对原始文本顺序要求更高的场景，比如合同条款、制度文件、考试题目等。

如果希望生成标准 Markdown 列表，可以根据实际需求调整列表导出模式，不一定都使用 Plain_Text。

3. 保留下划线格式

Markdown 原生语法对下划线支持并不统一。部分渲染器不支持直接显示下划线，或者需要借助 HTML 标签。

如果原 Word 文档中有比较重要的下划线内容，比如填空题、重点标记、表单字段，可以开启：

document.getMarkdownExportOptions().setSaveUnderlineFormatting(true);

这样可以尽量保留原文中的下划线格式。

4. 超链接输出方式

超链接可以直接写成行内链接，也可以写成引用式链接。

示例中使用的是引用式链接：

document.getMarkdownExportOptions().setLinkOutputMode(MarkdownLinkOutputMode.Reference);

引用式链接大致长这样：

这是一个 [示例链接][1]

[1]: https://example.com

如果一篇文档中链接很多，引用式链接会让正文看起来更干净。技术文档、论文说明、产品手册都比较适合这种方式。

5. 数学公式输出方式

如果 Word 文档中包含 Office Math 公式，可以设置公式导出方式：

document.getMarkdownExportOptions().setOfficeMathOutputMode(MarkdownOfficeMathOutputMode.Math_ML);

这里使用的是 Math_ML，表示将数学公式导出为 MathML。

需要注意的是，不同 Markdown 渲染器对 MathML 的支持并不完全一致。如果 Markdown 最终要放到某个平台上，建议先用一两个带公式的文档测试一下实际显示效果。

6. 表格使用 HTML 输出

Markdown 表格语法比较简单，适合普通二维表格。但 Word 里的表格可能包含合并单元格、复杂边框、多段文字等内容，这类表格直接转成 Markdown 表格后，格式可能会丢失。

示例中使用：

document.getMarkdownExportOptions().setSaveAsHtml(MarkdownSaveAsHtml.Tables);

这样表格会用 HTML 语法保存到 Markdown 中。

这种方式虽然会让 Markdown 内容变长，但对复杂表格更加稳妥。如果文档中有大量复杂表格，建议优先考虑这种设置。

五、路径写法注意点

在 Windows 中写路径时，反斜杠需要转义：

document.getMarkdownExportOptions().setImagesFolder("D:\\Markdown\\Images");

也可以使用正斜杠，代码会更清爽一些：

document.getMarkdownExportOptions().setImagesFolder("D:/Markdown/Images");

如果项目要部署到 Linux 服务器，建议把路径做成配置项，例如放到 application.yml 或环境变量中，不要直接写死在代码里。

六、常见问题

1. Markdown 转出来后图片不显示怎么办？

先检查三个地方：

图片是否真的导出到了指定目录；
Markdown 中的图片路径是否正确；
图片目录和 Markdown 文件的相对位置是否匹配。

如果 Markdown 后续要上传到博客平台，通常还需要把图片单独上传到图床或平台资源库，再替换 Markdown 中的图片路径。

2. 表格格式错乱怎么办？

如果 Word 表格比较复杂，建议开启 HTML 表格输出：

document.getMarkdownExportOptions().setSaveAsHtml(MarkdownSaveAsHtml.Tables);

Markdown 原生表格对复杂结构支持有限，尤其是合并单元格、嵌套内容、多行内容比较多的表格，很容易出现格式变化。

3. 列表编号和原文不一致怎么办？

可以先尝试调整列表输出模式：

document.getMarkdownExportOptions().setListOutputMode(MarkdownListOutputMode.Plain_Text);

如果文档更重视“看起来和 Word 一致”，可以使用普通文本模式。如果更重视“符合 Markdown 编辑习惯”，则可以保留 Markdown 列表语法。

4. 数学公式显示异常怎么办？

公式导出为 MathML 后，还要看目标平台是否支持 MathML 渲染。比如一些 Markdown 编辑器可以正常显示，而部分博客平台可能只会显示源码。

这种情况下可以考虑：

换成目标平台支持的公式格式；
将公式截图后作为图片处理；
在发布前手动检查带公式的段落。

5. Base64 图片适合所有场景吗？

不太建议所有场景都使用 Base64。

Base64 的优点是文件完整，不依赖外部图片；缺点是 Markdown 文件会明显变大，也不方便后期单独替换图片。

如果是临时传输、小型文档，可以考虑 Base64。如果是博客、知识库、项目文档，更建议把图片保存为独立文件。

七、总结

Word 转 Markdown 的基础逻辑并不复杂，核心就是：

document.loadFromFile("Data/toMarkdown.docx");
document.saveToFile("toMarkdown_out.md", FileFormat.Markdown);

真正影响转换质量的，往往是后面的导出选项。

如果文档比较简单，直接基础转换即可。如果文档包含图片、复杂表格、超链接、数学公式或特殊格式，就需要根据实际场景配置 Markdown 导出选项。

一般可以按下面的思路选择：

博客文章：图片单独导出，不建议 Base64；
技术文档：链接可以使用引用式链接；
复杂表格：建议用 HTML 表格输出；
带公式文档：提前测试目标平台对 MathML 的支持；
长期维护的文档：尽量保持 Markdown 文件简洁，图片和附件单独管理。

这样转换出来的 Markdown，后续无论是放到代码仓库、知识库，还是发布到博客平台，都会更容易维护。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

java

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

java

登录后参与评论

0 条评论

热度