SpringBoot 使用Docx4j实现 DOCX 转 PDF

文章目录

前言

在当今的企业级应用中，文档格式转换是一个高频但又容易被低估的需求。从合同签署、报表生成到知识库管理，DOCX转PDF的需求无处不在。市面上的解决方案五花八门，但真正能平衡"成本、质量、可维护性"的方案却寥寥无几。今天我们就介绍一款使用纯Java实现 DOCX 转 PDF的方案，超级简单，简直不要太爽。

Docx4j的核心优势

Docx4j之所以成为企业级应用的首选方案，主要得益于其以下核心优势：

1.纯Java实现：无需安装任何外部软件，部署简单

2.开源免费：采用Apache 2.0 License，可商用

3.样式保真度高：能完美保留Word文档中的图片、表格、页眉页脚等复杂格式

4.易于集成：可以无缝集成到SpringBoot项目中

实战演示

项目依赖配置

在pom.xml中添加docx4j相关依赖：

复制代码

<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-core</artifactId>
    <!-- 使用兼容 Java 8 的版本  Java 11  11.4.8-->
    <version>8.3.4</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-JAXB-ReferenceImpl</artifactId>
    <version>8.3.4</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-export-fo</artifactId>
    <version>8.3.4</version>
</dependency>

核心工具类

创建DocxToPdfUtil工具类，封装DOCX转PDF的核心逻辑：

复制代码

/**
 * DocxToPdfUtil
 * @author senfel
 * @version 1.0
 * @date 2026/2/4 17:21
 */
@Slf4j
public class DocxToPdfUtil {
    /**
     * 将docx文件转换为 PDF
     * @param docxPath
     * @param pdfPath
     * @author senfel
     * @date 2026/2/4 17:22
     * @return void
     */
    public static void convert(String docxPath, String pdfPath) {
        try {
            // 1. 加载 Word 文档
            WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(new File(docxPath));
            // 2. 配置字体映射（防止中文乱码）
            Mapper fontMapper = new IdentityPlusMapper();
            PhysicalFonts.discoverPhysicalFonts();
            PhysicalFont simsun = PhysicalFonts.get("SimSun");
            if (simsun != null) {
                fontMapper.put("SimSun", simsun);
                // 常用中文字体映射表
                fontMapper.put("隶书", PhysicalFonts.get("LiSu"));
                fontMapper.put("宋体", PhysicalFonts.get("SimSun"));
                fontMapper.put("微软雅黑", PhysicalFonts.get("Microsoft YaHei"));
                fontMapper.put("黑体", PhysicalFonts.get("SimHei"));
                fontMapper.put("楷体", PhysicalFonts.get("KaiTi"));
                fontMapper.put("新宋体", PhysicalFonts.get("NSimSun"));
                fontMapper.put("华文行楷", PhysicalFonts.get("STXingkai"));
                fontMapper.put("华文仿宋", PhysicalFonts.get("STFangsong"));
                fontMapper.put("仿宋", PhysicalFonts.get("FangSong"));
                fontMapper.put("幼圆", PhysicalFonts.get("YouYuan"));
                fontMapper.put("华文宋体", PhysicalFonts.get("STSong"));
                fontMapper.put("华文中宋", PhysicalFonts.get("STZhongsong"));
                fontMapper.put("等线", PhysicalFonts.get("SimSun"));
                fontMapper.put("等线 Light", PhysicalFonts.get("SimSun"));
                fontMapper.put("华文琥珀", PhysicalFonts.get("STHupo"));
                fontMapper.put("华文隶书", PhysicalFonts.get("STLiti"));
                fontMapper.put("华文新魏", PhysicalFonts.get("STXinwei"));
                fontMapper.put("华文彩云", PhysicalFonts.get("STCaiyun"));
                fontMapper.put("方正姚体", PhysicalFonts.get("FZYaoti"));
                fontMapper.put("方正舒体", PhysicalFonts.get("FZShuTi"));
                fontMapper.put("华文细黑", PhysicalFonts.get("STXihei"));
                fontMapper.put("宋体扩展", PhysicalFonts.get("simsun-extB"));
                fontMapper.put("仿宋_GB2312", PhysicalFonts.get("FangSong_GB2312"));
                fontMapper.put("新細明體", PhysicalFonts.get("SimSun"));
                // 修复体（正文）/宋体（标题乱码
                PhysicalFonts.put("PMingLiU", PhysicalFonts.get("SimSun"));
                PhysicalFonts.put("新細明體", PhysicalFonts.get("SimSun"));
                wordMLPackage.setFontMapper(fontMapper);
            }
            // 3. 创建输出流并执行转换
            try (FileOutputStream os = new FileOutputStream(pdfPath)) {
                Docx4J.toPDF(wordMLPackage, os);
            }
            log.info("PDF 生成成功：{}" ,pdfPath);
        } catch (Exception e) {
            log.error("转换失败：{}",e.getMessage(),e);
        }
    }
}

测试用例

创建类DocxToPdfTest，验证提供DOCX转PDF的工具类：

复制代码

/**
 * DocxToPdfTest
 * @author senfel
 * @version 1.0
 * @date 2026/2/4 17:26
 */
@SpringBootTest
public class DocxToPdfTest {


    /**
     * covertTest
     * @author senfel
     * @date 2026/2/4 17:27
     * @return void
     */
    @Test
    public void covertTest() {
        String docxPath = "D:\\blank\\小程序简介中英文.docx";
        String pdfPath = "D:\\blank\\小程序简介中英文.pdf";
        DocxToPdfUtil.convert(docxPath, pdfPath);
    }
}

解决中文乱码

Windows

在Windows环境中，中文乱码主要是由于字体映射问题导致的。我们需要在工具类中添加中文字体映射表，确保docx4j能够正确识别和转换中文字体。

Linux

在Linux环境中，中文乱码问题更为复杂，需要安装Windows字体。具体步骤如下：

1.新建字体文件夹：

复制代码

sudo mkdir -p /usr/share/fonts/win_font

2.拷贝Windows字体文件：将Windows系统中路径为C:\Windows\Fonts的字体文件拷贝到Linux的/usr/share/fonts/win_font目录中。

3.加载字体文件：

复制代码

cd /usr/share/fonts/win_font
sudo mkfontscale     # 生成字体缩放文件
sudo mkfontdir       # 生成字体目录索引
sudo fc-cache -fv    # 刷新字体缓存

4.验证字体安装：

复制代码

fc-list :lang=zh

总结

Docx4j是一个优秀的开源文档处理工具，它为SpringBoot项目提供了一种轻量级、高性能的DOCX转PDF解决方案。通过本文的介绍，我们了解了docx4j的核心优势、并使用springboot实战落了一个简单的案例。在实际项目中，我们可以根据业务需求和技术选型战略，选择最适合的文档转换方案。对于大多数企业级应用来说，Docx4j无疑是一个性价比极高的选择。