Docx4J跨系统转换LibreOffice/Word生成的docx为pdf出现artifacts问题求助

针对跨操作系统（Windows/Linux）、不同编辑器（LibreOffice/MS Word）生成的docx模板转换PDF时出现######!这类异常字符的问题，可通过以下配置和调整解决：

1. 统一字体映射配置 #

Docx4J的PDF渲染依赖系统字体，跨系统字体缺失或不一致是核心问题之一。需强制指定字体映射，确保转换时使用兼容字体：

// 初始化字体映射器
FontMapper fontMapper = new IdentityPlusMapper();
// 加载跨平台通用字体（如Arial），替换模板中的系统特定字体
PhysicalFont universalFont = PhysicalFonts.get("Arial");
if (universalFont != null) {
    fontMapper.put("Liberation Serif", universalFont); // 适配LibreOffice默认字体
    fontMapper.put("Times New Roman", universalFont); // 适配MS Word默认字体
}
// 绑定字体映射到文档包
wordprocessingMLPackage.setFontMapper(fontMapper);

若需避免目标系统无对应字体的问题，可开启字体嵌入：

((IdentityPlusMapper)fontMapper).setEmbedFonts(true);
((IdentityPlusMapper)fontMapper).setEmbedAsSubset(true);

2. 优化PDF转换参数 #

通过ConversionOptions调整渲染逻辑，禁用可能引发跨系统兼容问题的特性：

ConversionOptions options = ConversionOptions.getDefault();
options.setWmlPackage(wordprocessingMLPackage);
options.setSaveFO(false); // 避免FO格式转换的兼容性冲突
// 执行转换
Docx4J.toPDF(wordprocessingMLPackage, reportStream, options);

3. 规范模板格式 #

• 替换模板中的系统专属特殊字符、样式为标准Unicode字符和通用格式
• 统一使用跨平台通用字体（如Arial、Calibri），避免依赖Liberation系列、微软雅黑等仅部分系统预装的字体

4. 保持依赖版本一致 #

确保Windows和Linux环境使用完全相同版本的Docx4J依赖，版本差异可能导致渲染逻辑不一致。Maven依赖示例：

<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-core</artifactId>
    <version>11.4.9</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-pdf-export</artifactId>
    <version>11.4.9</version>
</dependency>

内容的提问来源于stack exchange，提问作者ks_on_v