使用Docx4j非XSL转换DOCX到PDF时出现空指针异常

问题场景 #

刚接触Docx4j，尝试将DOCX文件转换为PDF，为缩短约2分钟的转换耗时，采用非XSL转换方式（Docx4J.FLAG_EXPORT_PREFER_NONXSL），但遇到图片处理相关空指针异常：

java.lang.NullPointerException: Cannot invoke "org.docx4j.model.images.WordXmlPictureE20.createXslFoImageElement()" because "converter" is null
at org.docx4j.model.images.WordXmlPictureE20.createXslFoImgE20 (WordXmlPictureE20.java)

相关转换代码：

import java.io.File;
import java.io.FileOutputStream;
import java.io.OutputStream;
import org.docx4j.Docx4J;
import org.docx4j.convert.out.FOSettings;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

public class DocxToPDFConverter {

    public static void convertToPDF(File docxFile, File pdfFile) throws Exception {
        // Load the DOCX into a WordprocessingMLPackage
        WordprocessingMLPackage wordMLPackage = Docx4J.load(docxFile);
        wordMLPackage.setFontMapper(new BestMatchingMapper());

        // Configure FO settings
        FOSettings foSettings = Docx4J.createFOSettings();
        foSettings.setWmlPackage(wordMLPackage);
        foSettings.setApacheFopMime(FOSettings.MIME_PDF);

        // Prepare the output stream
        try (OutputStream out = new FileOutputStream(pdfFile)) {
            // Convert to PDF with non-XSL transformation
            Docx4J.toFO(foSettings, out, Docx4J.FLAG_EXPORT_PREFER_NONXSL);
        }
    }
}

已尝试的措施：

• 确保classpath包含所需jar包，pom.xml引入11.4.9版本的docx4j-JAXB-ReferenceImpl、docx4j-export-fo；
• 尝试FLAG_EXPORT_PREFER_NONXSL提速，但因异常未生效；
• 检查Docx4J默认图片处理器。

问题 #

1. 如何修复"converter is null"异常，完成DOCX到PDF的转换？
2. 使用Docx4J.toPDF()转换时，还有哪些优化方式可缩短响应时间？已尝试非XSL转换但性能提升不足。

环境：Java 17，Docx4J版本11.4.9（已引入docx4j-export-fo）

一、修复"converter is null"空指针异常 #

该异常是因为非XSL转换模式下，图片转换器未被正确初始化导致的，可通过以下方式解决：

1. 手动初始化图片转换器 #

在配置FOSettings后，显式设置图片转换器实例，添加代码到foSettings.setApacheFopMime(...)之后：

import org.docx4j.model.images.WordXmlPictureE20;
import org.docx4j.convert.out.fo.renderers.FORendererApacheFOP;

// 初始化图片转换器
WordXmlPictureE20.setConverter(new FORendererApacheFOP.ImageConverter(foSettings));

2. 确认依赖完整性 #

确保pom.xml中引入完整的docx4j-export-fo依赖，无组件缺失：

<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-export-fo</artifactId>
    <version>11.4.9</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-JAXB-ReferenceImpl</artifactId>
    <version>11.4.9</version>
</dependency>

3. 临时切换转换模式（Workaround） #

如果上述方法无效，可暂时使用默认XSL转换模式保证转换成功，后续再优化性能：

Docx4J.toFO(foSettings, out, Docx4J.FLAG_EXPORT_NONE);

二、DOCX转PDF性能优化建议 #

除非XSL转换外，还可通过以下方式进一步缩短耗时：

1. 启用并行处理 #

通过FOSettings开启并行处理文档元素，利用多核CPU提升效率：

foSettings.setUseParallelProcessing(true);

注意：并行处理会增加内存消耗，需根据服务器配置调整。

2. 优化字体加载 #

• 用IdentityPlusMapper替代BestMatchingMapper，减少字体匹配耗时：

wordMLPackage.setFontMapper(new IdentityPlusMapper());

• 预加载常用字体，避免每次转换重复加载：

IdentityPlusMapper fontMapper = new IdentityPlusMapper();
fontMapper.put("宋体", PhysicalFonts.get("SimSun"));
fontMapper.put("微软雅黑", PhysicalFonts.get("Microsoft YaHei"));
wordMLPackage.setFontMapper(fontMapper);

3. 关闭文档验证 #

关闭Docx4j的文档验证功能，减少加载阶段的耗时：

Docx4J.setValidation(false);

4. 优化IO操作 #

先写入内存流再一次性写入磁盘，减少磁盘IO次数：

try (ByteArrayOutputStream baos = new ByteArrayOutputStream();
     FileOutputStream out = new FileOutputStream(pdfFile)) {
    Docx4J.toFO(foSettings, baos, Docx4J.FLAG_EXPORT_PREFER_NONXSL);
    baos.writeTo(out);
}

5. 升级Docx4j版本 #

新版本通常会修复性能瓶颈和已知bug，可尝试升级到最新稳定版，优化非XSL转换的图片处理逻辑。

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