Java Word转PDF中文乱码如何解决？

Question

在使用Java将Word文档转换为PDF时，常因字体未正确嵌入或系统缺少中文字体导致中文乱码。典型表现为方块、问号或空白字符。该问题多出现在基于Apache POI+iText或Jacob调用Office组件的方案中。核心原因包括：未指定中文字体（如宋体、微软雅黑），PDF生成时未启用字体嵌入，或服务器环境缺失GUI字体支持。如何确保转换过程中正确加载并嵌入中文字体，成为解决乱码的关键技术难点。

Answer 1

一、问题背景与现象分析

在Java应用中，将Word文档（.doc或.docx）转换为PDF格式是一项常见需求，尤其在企业级文档管理系统、电子合同平台和报表生成系统中广泛应用。然而，在实际转换过程中，中文乱码问题频繁出现，表现为汉字显示为方块（□）、问号（？）或空白字符。

该问题主要出现在以下技术栈中：

• Apache POI + iText / PDFBox 用于解析Word并生成PDF
• Jacob 桥接调用 Windows 系统的 Microsoft Office 组件进行转换
• LibreOffice 或 OpenOffice 的 headless 模式通过命令行调用

尽管这些方案在英文环境下运行稳定，但在处理含中文内容的文档时，常因字体未正确加载或嵌入而引发乱码。

二、核心成因剖析

中文乱码的根本原因可归结为以下三类：

1. 未显式指定中文字体：iText等库默认使用Helvetica等西文字体，不支持中文字符集。
2. 字体未嵌入PDF：即使指定了字体路径，若未启用BaseFont.EMBEDDED，生成的PDF依赖客户端系统字体，跨平台易出错。
3. 服务器环境缺失中文字体文件：Linux服务器通常缺少Windows自带的“宋体”、“微软雅黑”等字体，导致字体查找失败。

此外，Apache POI本身仅负责读取Word结构，不处理渲染；真正决定输出样式的是下游PDF生成库，因此字体配置必须在PDF生成阶段完成。

三、解决方案层级递进

层级	技术手段	适用场景	是否解决乱码
L1 - 应用层	设置字体路径与编码	开发测试环境	部分
L2 - 运行时层	注册字体到JVM字体管理器	Linux服务器部署	是
L3 - 转换引擎层	使用Docx4j + PDF/HTML中间格式	高保真转换需求	是
L4 - 系统层	安装中文字体包（如wqy-zenhei）	Docker/K8s环境	基础保障

四、典型代码实现示例

        
// 使用iText 7嵌入本地中文字体
public void convertWithChineseFont() throws IOException {
    PdfWriter writer = new PdfWriter("output.pdf");
    PdfDocument pdfDoc = new PdfDocument(writer);
    Document document = new Document(pdfDoc);

    // 加载微软雅黑字体，启用嵌入
    String fontPath = "/usr/share/fonts/truetype/msyh.ttc"; // Linux路径示例
    PdfFont font = PdfFontFactory.createFont(fontPath, "Identity-H", true);

    document.setFont(font);
    document.add(new Paragraph("这是一段测试中文内容"));

    document.close();
}
        
    

上述代码关键点在于："Identity-H" 编码支持Unicode中文，true 参数表示嵌入字体。

五、流程图：中文字体处理完整链路

graph TD
            A[读取Word文档] --> B{是否含中文?}
            B -- 是 --> C[加载中文字体文件]
            B -- 否 --> D[使用默认字体]
            C --> E[创建PDF字体对象并嵌入]
            E --> F[设置段落字体]
            F --> G[写入PDF内容]
            G --> H[关闭文档流]
            H --> I[输出PDF文件]
            style C fill:#ffe4b5,stroke:#333
            style E fill:#98fb98,stroke:#333

六、高级策略与生产建议

对于大规模文档服务系统，推荐采用如下组合策略：

• 构建Docker镜像时预装中文字体（如Microsoft Core Fonts或WenQuanYi Micro Hei）
• 使用GraphicsEnvironment验证字体注册状态
• 对Docx文档中的每个文本段落动态匹配原始字体，并映射到可用中文字体
• 结合docx4j导出为FO（Formatting Objects）再转PDF，保留更多排版信息
• 启用日志记录字体加载过程，便于排查ClassNotFoundException或IOException
• 在CI/CD流水线中加入PDF抽样检测脚本，自动识别乱码
• 考虑使用Headless Chrome进行HTML转PDF作为替代方案
• 缓存已加载字体实例，避免重复IO开销
• 对用户上传的字体文件做安全校验，防止恶意TTF注入
• 监控JVM字体资源占用，防止内存泄漏