docx4j文档中文乱码如何解决？

Question

在使用docx4j生成或导出Word文档时，常出现中文乱码问题，主要表现为导出的文档中中文显示为方框、问号或空白。该问题通常由字符编码设置不当引起，尤其是在将Document对象转换为输出流时未指定UTF-8编码。此外，模板文件本身编码不兼容或字体未正确嵌入也会导致乱码。如何正确配置输出流的编码并确保模板支持中文字符，是解决docx4j中文乱码的关键所在。

Answer 1

1. 中文乱码问题的表象与常见场景

在使用 docx4j 生成或导出 Word 文档时，中文乱码是高频出现的问题之一。典型表现为：文档中的中文字符显示为方框（□）、问号（？）或完全空白。这类问题多出现在以下场景：

• 从 Java 后端导出基于模板的 .docx 文件
• 动态插入中文文本、表格数据或段落内容
• 跨平台部署（如 Windows 开发，Linux 生产环境运行）
• 使用非 UTF-8 编码的模板文件

虽然 docx4j 基于 OpenXML 标准，理论上支持 Unicode 字符集，但实际应用中若未正确处理编码和字体配置，仍会导致中文无法正常渲染。

2. 根本原因分析：从字符编码到字体嵌入

要深入理解乱码成因，需从以下几个层面进行剖析：

1. 输出流编码未指定 UTF-8：Java 默认字符集可能为 ISO-8859-1 或平台相关编码，导致中文字符在序列化过程中被错误转换。
2. 模板文件本身编码不兼容：即使 .docx 是 ZIP 容器，其内部 XML 文件若以 ANSI 或 GBK 编码保存，解析时将丢失中文信息。
3. 字体未正确声明或缺失：Word 渲染时若找不到对应中文字体（如宋体、微软雅黑），会回退至不支持中文的字体，造成方框显示。
4. JVM 默认编码影响：启动参数未设置 -Dfile.encoding=UTF-8 时，系统属性可能干扰 I/O 流编码判断。

3. 解决方案路径图示

```mermaid
graph TD
    A[开始导出文档] --> B{是否使用模板?}
    B -- 是 --> C[确认模板文件UTF-8编码]
    B -- 否 --> D[构建Document对象]
    C --> E[加载模板为WordprocessingMLPackage]
    D --> F[设置文档字符集为UTF-8]
    E --> G[插入中文内容]
    F --> G
    G --> H[配置输出流编码]
    H --> I[写入OutputStream并指定UTF-8]
    I --> J[关闭流并测试预览]
    J --> K[验证中文字体存在性]
    K --> L[完成导出]
```

4. 关键代码实现：确保 UTF-8 编码贯穿全流程

以下是解决乱码的核心代码段，重点在于输出流的编码控制与文档属性设置：

// 加载模板（确保模板本身为UTF-8编码）
WordprocessingMLPackage wordPackage = WordprocessingMLPackage.load(new File("template.docx"));

// 设置文档默认字体（推荐支持中文的字体）
ObjectFactory factory = Context.getWmlObjectFactory();
RPr rpr = factory.createRPr();
rpr.setRFonts(factory.createRFonts());
rpr.getRFonts().setAscii("SimSun");
rpr.getRFonts().setEastAsia("SimSun"); // 设置东亚字体
rpr.getRFonts().setHAnsi("SimSun");

// 插入中文文本时显式设置语言属性
P paragraph = createParagraphWithString("这是一段中文内容", rpr);
wordPackage.getMainDocumentPart().addParagraph(paragraph);

// 导出时指定UTF-8编码的输出流
OutputStream os = new FileOutputStream("output.docx");
Docx4J.save(wordPackage, os, Docx4J.FLAG_SAVE_ONLY_XML); 
os.flush();
os.close(); // 注意：此处 save 方法依赖底层 JAXB 序列化，默认应使用 UTF-8

5. 模板文件的最佳实践建议

检查项	推荐做法	工具/方法
模板创建环境	使用 Microsoft Word 新建并保存，避免第三方编辑器乱码	Office 2016+
默认中文字体	设置正文样式为“宋体”或“微软雅黑”	修改 Normal 样式
内部 XML 编码	解压 .docx 查看 document.xml 是否含中文且无乱码	zip -d template.docx
语言区域设置	将文档语言设为“中文(中国)”	Word > 审阅 > 语言
嵌入字体选项	启用“将字体嵌入文件”以提高兼容性	另存为 > 工具 > 保存选项

6. JVM 与系统级编码调优

即便代码层已处理 UTF-8，JVM 层面的默认编码仍可能引发隐患。建议在启动脚本中强制设定：

-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8

可通过以下代码验证当前环境编码：

System.out.println("Default Charset: " + Charset.defaultCharset());
System.out.println("File Encoding: " + System.getProperty("file.encoding"));
System.out.println("Sun JNU Encoding: " + System.getProperty("sun.jnu.encoding"));

生产环境中应统一所有节点的编码策略，避免因服务器差异导致偶发乱码。

7. 高级调试技巧：定位乱码源头

当问题难以复现时，可采用以下手段逐层排查：

• 解压生成的 .docx 文件，查看 word/document.xml 中中文是否已乱码 —— 若是，则问题出在生成阶段；否则可能是客户端渲染问题。
• 使用 Docx4J.FLAG_DEBUG 标志启用详细日志输出。
• 通过 org.docx4j.convert.out.html.HTMLSettings 将文档转为 HTML 进行比对。
• 利用 Apache Tika 提取文本内容，验证原始字符完整性。

还可编写单元测试模拟不同编码输入，验证系统的健壮性。