告别乱码！手把手教你用docx4j实现Word转PDF（附完整中文字体配置）

告别乱码！手把手教你用docx4j实现Word转PDF（附完整中文字体配置）

你是否曾在深夜调试代码时，被Word转PDF后满屏的“口口口”乱码折磨得焦头烂额？或者好不容易在Windows上跑通了转换流程，一部署到Linux服务器上，原本工整的宋体标题就变成了无法识别的方框？如果你正在为中文文档的精准转换而苦恼，那么这篇文章正是为你准备的。

在企业级应用开发中，将Word文档转换为PDF是一个极其常见的需求——无论是合同归档、报告生成，还是内容预览与分发，PDF格式的稳定性和跨平台一致性都是不可替代的。然而，当文档中充斥着中文内容时，这个看似简单的任务往往会演变成一场字体兼容性的噩梦。传统的解决方案，如依赖系统Office组件的Jacob方案受限于Windows平台，而调用LibreOffice命令行又面临部署复杂、资源占用高的挑战。有没有一种既跨平台、又轻量集成，还能完美支持中文排版的方案呢？

答案是肯定的。docx4j，这个纯Java实现的Word文档处理库，正是解决这一痛点的利器。它不依赖任何外部进程或系统字体服务，完全在JVM内完成从.docx解析到PDF渲染的全过程，理论上可以实现“一次编写，处处运行”的理想状态。但理论归理论，实际落地时，中文字体的配置、Linux环境的适配、复杂样式的保真，每一个环节都可能让你踩坑。本文将从一个实战开发者的角度，带你深入docx4j的核心，不仅提供可运行的代码，更会剖析背后的原理，让你彻底掌握中文Word转PDF的完整解决方案。无论你是需要处理中文合同的技术团队，还是负责报告系统开发的工程师，这篇文章都将为你提供从环境搭建到生产部署的全套指南。

1. 环境准备与依赖配置

在开始编码之前，我们需要先搭建一个干净、可复现的开发环境。docx4j虽然是一个纯Java库，但其依赖关系相对复杂，特别是涉及到PDF导出功能时，需要引入正确的模块组合。

1.1 项目依赖配置

对于Maven项目，你需要在pom.xml中添加以下核心依赖：

<!-- docx4j核心库 -->
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-JAXB-Internal</artifactId>
    <version>8.3.9</version>
</dependency>

<!-- PDF导出模块 -->
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-export-fo</artifactId>
    <version>8.3.9</version>
</dependency>

<!-- 可选：日志实现 -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.9</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.4.11</version>
</dependency>

这里有几个关键点需要注意：

• 版本一致性：确保所有docx4j相关组件的版本号保持一致，不同版本间的API可能存在不兼容的情况。
• JAXB实现选择：docx4j提供了JAXB-Internal和JAXB-ReferenceImpl两种选择。前者内置了JAXB实现，更适合独立部署；后者依赖JDK或外部JAXB实现。对于大多数场景，使用JAXB-Internal更为稳妥。
• 日志依赖：docx4j内部使用SLF4J作为日志门面，你需要提供一个具体的日志实现（如Logback），否则在运行时可能会看到警告信息。

1.2 环境兼容性检查

docx4j对运行环境的要求相对宽松，但为了确保最佳兼容性，建议满足以下条件：

注意：虽然docx4j号称跨平台，但字体配置是跨平台部署中最容易出问题的环节。在Windows开发机上运行正常的代码，部署到Linux服务器后可能会出现中文乱码，这是因为Linux系统默认不包含Windows常用的中文字体。

1.3 开发工具准备

为了高效开发和调试，我建议配置以下工具：

1. IDE选择：IntelliJ IDEA或Eclipse均可，确保已安装Lombok插件（如果使用Lombok注解）。
2. 测试文档准备：准备几个具有代表性的测试文档，包括：
   • 简单中文文档（仅包含宋体、微软雅黑）
   • 复杂格式文档（包含表格、图片、页眉页脚）
   • 混合字体文档（中英文混排，多种字体样式）
3. 字体查看工具：在Linux上可以使用fc-list命令查看已安装的字体，在Windows上可以通过控制面板的字体设置查看。

我个人的经验是，在项目初期就建立一套完整的测试用例，覆盖各种边界情况。这样当你在不同环境间迁移时，可以快速验证转换效果是否一致。比如，我曾经遇到过一个诡异的问题：在开发环境转换正常，但在测试环境却出现部分文字缺失。后来发现是因为测试环境的Linux服务器缺少“仿宋_GB2312”字体，而开发文档中恰好使用了这种字体。

2. 核心转换流程与代码实现

理解了环境配置后，我们来深入docx4j的核心转换流程。这个过程看似简单——加载Word文档，设置字体映射，输出PDF——但每个环节都有需要注意的细节。

2.1 基础转换代码框架

让我们从一个最基础的转换示例开始：

import org.docx4j.Docx4J;
import org.docx4j.fonts.IdentityPlusMapper;
import org.docx4j.fonts.Mapper;
import org.docx4j.fonts.PhysicalFonts;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import java.io.File;
import java.io.FileOutputStream;

public class WordToPdfConverter {
    
    public static void convertDocxToPdf(String sourcePath, String targetPath) throws Exception {
        // 1. 加载Word文档
        WordprocessingMLPackage wordMLPackage = Docx4J.load(new File(sourcePath));
        
        // 2. 创建字体映射器并配置中文字体
        Mapper fontMapper = new IdentityPlusMapper();
        configureChineseFonts(fontMapper);
        wordMLPackage.setFontMapper(fontMapper);
        
        // 3. 执行PDF转换
        try (FileOutputStream fos = new FileOutputStream(targetPath)) {
            Docx4J.toPDF(wordMLPackage, fos);
            System.out.println("转换成功: " + targetPath);
        }
    }
    
    private static void configureChineseFonts(Mapper fontMapper) {
        // 基础中文字体映射
        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("FangSong"));
        
        // 处理常见的字体别名
        fontMapper.put("SimSun", PhysicalFonts.get("SimSun"));
        fontMapper.put("NSimSun", PhysicalFonts.get("SimSun")); // 新宋体映射到宋体
        fontMapper.put("Microsoft YaHei", PhysicalFonts.get("Microsoft YaHei"));
    }
}

这段代码虽然简单，但已经包含了转换的核心逻辑。不过，在实际生产环境中，我们需要考虑更多的异常情况和性能优化。

2.2 增强版的转换工具类

下面是一个更加健壮、适合生产环境使用的工具类实现：

import lombok.extern.slf4j.Slf4j;
import org.docx4j.Docx4J;
import org.docx4j.fonts.IdentityPlusMapper;
import org.docx4j.fonts.Mapper;
import org.docx4j.fonts.PhysicalFont;
import org.docx4j.fonts.PhysicalFonts;
import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import java.io.*;
import java.util.HashMap;
import java.util.Map;

@Slf4j
public class AdvancedWordToPdfConverter {
    
    // 字体映射缓存，避免重复创建
    private static volatile Mapper fontMapper;
    
    /**
     * 将Word文档转换为PDF（支持输入输出流）
     */
    public static void convert(InputStream docxInput, OutputStream pdfOutput) 
            throws Docx4JException, IOException {
        long startTime = System.currentTimeMillis();
        
        try {
            // 加载文档
            WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(docxInput);
            
            // 设置字体映射
            wordMLPackage.setFontMapper(getOrCreateFontMapper());
            
            // 执行转换
            Docx4J.toPDF(wordMLPackage, pdfOutput);
            
            long cost = System.currentTimeMillis() - startTime;
            log.info("Word转PDF成功，耗时: {}ms", cost);
            
        } catch (Exception e) {
            log.error("Word转PDF失败", e);
            throw new Docx4JException("转换失败: " + e.getMessage(), e);
        } finally {
            // 确保资源关闭
            if (docxInput != null) {
                try { docxInput.close(); } catch (IOException ignored) {}
            }
        }
    }
    
    /**
     * 单例模式获取字体映射器
     */
    private static synchronized Mapper getOrCreateFontMapper() {
        if (fontMapper == null) {
            fontMapper = new IdentityPlusMapper();
            initChineseFontMapping(fontMapper);
        }
        return fontMapper;
    }
    
    /**
     * 初始化中文字体映射
     */
    private static void initChineseFontMapping(Mapper mapper) {
        // 常见中文字体映射表
        Map<String, String> fontMapping = new HashMap<>();
        
        // Windows常用字体
        fontMapping.put("宋体", "SimSun");
        fontMapping.put("新宋体", "NSimSun");
        fontMapping.put("黑体", "SimHei");
        fontMapping.put("楷体", "KaiTi");
        fontMapping.put("仿宋", "FangSong");
        fontMapping.put("微软雅黑", "Microsoft YaHei");
        fontMapping.put("微软雅黑 Light", "Microsoft YaHei Light");
        
        // 华文字体系列
        fontMapping.put("华文宋体", "STSong");
        fontMapping.put("华文黑体", "STHeiti");
        fontMapping.put("华文楷体", "STKaiti");
        fontMapping.put("华文仿宋", "STFangsong");
        
        // 方正字体系列
        fontMapping.put("方正姚体", "FZYaoti");
        fontMapping.put("方正舒体", "FZShuTi");
        
        // 处理字体别名和变体
        fontMapping.put("SimSun", "SimSun");
        fontMapping.put("SimSun-ExtB", "SimSun"); // 扩展B区
        fontMapping.put("PMingLiU", "SimSun");    // 繁体明体
        
        // 应用映射
        for (Map.Entry<String, String> entry : fontMapping.entrySet()) {
            String logicalName = entry.getKey();
            String physicalName = entry.getValue();
            PhysicalFont font = PhysicalFonts.get(physicalName);
            if (font != null) {
                mapper.put(logicalName, font);
                log.debug("已映射字体: {} -> {}", logicalName, physicalName);
            } else {
                log.warn("字体未找到: {} (映射为: {})", logicalName, physicalName);
            }
        }
    }
    
    /**
     * 批量转换入口
     */
    public static void batchConvert(String sourceDir, String targetDir, String filePattern) {
        File dir = new File(sourceDir);
        if (!dir.exists() || !dir.isDirectory()) {
            throw new IllegalArgumentException("源目录不存在: " + sourceDir);
        }
        
        File[] files = dir.listFiles((d, name) -> name.matches(filePattern));
        if (files == null || files.length == 0) {
            log.warn("未找到匹配的文件: {}", filePattern);
            return;