Java 后端处理 Markdown：导出 Word 与 PDF 的方法记录

在日常技术写作中，Markdown 是常用格式。但在交付给产品经理、客户或归档时，Word 和 PDF 格式更为常见。手动逐个转换效率较低，也难以集成到自动化流程中。

本文记录在 Java 后端环境中，借助 Spire.Doc for Java 库，将 Markdown 转换为 Word 和 PDF 的方法。

该库为商业组件，提供免费版和试用版。以下示例基于免费版运行，输出的文档会带有评估水印。生产环境部署前，开发者需要自行了解授权相关信息。

一、方案简述

在 Java 生态中，处理 Markdown 转 Word/PDF 的常见方式有：

Pandoc 命令行调用：转换质量较高，但需要服务器安装 Pandoc 环境
OpenOffice 无头模式：稳定性较好，但部署资源占用较大
文档处理库直接调用：不依赖本地 Office，API 相对简洁

第三种方案在这方面有一定优势，适合需要嵌入到后端服务中的场景。

二、环境配置

项目环境要求：

JDK 1.8 及以上
Maven 3.x 或 Gradle

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

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

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

不使用 Maven 时，也可手动下载 JAR 包并添加到项目 classpath。

三、Markdown 转 Word

转换逻辑：使用 Document 对象加载 Markdown 文件，然后保存为 Docx 格式。

import com.spire.doc.Document;
import com.spire.doc.FileFormat;

public class MdToWord {

    public static void main(String[] args) {
        Document doc = new Document();
        doc.loadFromFile("/data/docs/readme.md", FileFormat.Markdown);
        doc.saveToFile("/data/output/readme.docx", FileFormat.Docx);
        doc.dispose();
        System.out.println("转换完成");
    }
}

转换后，标题（H1-H6）、列表、粗体斜体、代码块等基础样式会保留。表格转换基本可用，但若原始 Markdown 表格格式不规范（如分隔线与列数不对应），可能出现样式偏差。

四、Markdown 转 PDF

PDF 转换方式与 Word 类似，仅修改保存格式参数：

import com.spire.doc.Document;
import com.spire.doc.FileFormat;

public class MdToPdf {

    public static void main(String[] args) {
        Document doc = new Document();
        doc.loadFromFile("/data/docs/api文档.md", FileFormat.Markdown);
        doc.saveToFile("/data/output/api文档.pdf", FileFormat.PDF);
        doc.dispose();
    }
}

PDF 的页面样式（纸张大小、页边距、横竖版）默认为 Letter + 纵向。如需调整，可在保存前修改 Section 配置：

Section section = doc.getSections().get(0);
PageSetup ps = section.getPageSetup();

ps.setPageSize(PageSize.A4);                  // A4纸张
ps.setOrientation(PageOrientation.Landscape); // 横向布局

五、使用中可能遇到的问题

5.1 图片不显示

Markdown 中的本地图片（如 [图片上传失败...(image-b186cc-1777428003262)]）转换后可能不显示。原因是库在解析相对路径时依赖于当前工作目录，如果程序运行目录与 Markdown 文件所在目录不一致，图片无法被找到。

处理方式：将图片转换为可公网访问的 URL，或将图片与 Markdown 文件放在同一目录层级。

5.2 扩展语法不支持

该库主要覆盖标准 Markdown 语法。如果文档中包含 Mermaid 流程图、LaTeX 数学公式等扩展语法，转换后这些位置可能为空白或显示原始代码。

5.3 水印

免费版输出的文档会带有评估水印。内部测试可接受，正式交付则需要考虑授权。

5.4 内存占用

处理大文件（超过 20MB）时，可通过 JVM 参数 -Xmx2g 增加堆内存。

六、适用场景

该转换逻辑可封装为工具类，接入以下场景：

Git 钩子触发：推送 Markdown 文档后自动生成 PDF
后台管理导出：提供“导出 Word/PDF”功能按钮
文档交付流程：将 Markdown 格式的 API 文档转为通用格式

以上场景均已有实际项目验证，运行正常。

七、小结

在 Java 中完成 Markdown 向 Word 和 PDF 的转换，核心步骤为：选择文档处理库 → 加载 Markdown → 保存为目标格式。

Spire.Doc for Java 的 API 较为简洁，不依赖本地 Office 软件，适合后端集成。其局限性包括商业授权、扩展语法支持范围有限、免费版带水印。是否选用，取决于具体项目需求和预算。

如果是少数文件的转换，手动使用 Pandoc 或编辑器导出更快捷；如果需要将转换能力集成到自动化系统中，本文记录的方法可以作为参考。

Java 后端处理 Markdown：导出 Word 与 PDF 的方法记录