问题描述
在使用Docx4j库将Word文档（.docx）转换为PDF时，如果文档中包含图片，Docx4j会利用XSL-FO（Extensible Stylesheet Language - Formatting Objects）和Apache FOP（Formatting Objects Processor）进行渲染。在此过程中，图片通常会被临时存储到文件系统中。Docx4j提供了FOSettings.setImageDirPath()方法，允许开发者指定一个临时图片存储目录，并在转换完成后手动清理该目录。
然而，实践中发现，尽管为FOSettings设置了ImageDirPath，但文档主体（body）中的图片会按预期存储到指定目录，而位于页眉（header）或页脚（footer）中的图片却依然会被存储到操作系统的默认临时目录（例如Linux上的/tmp）。更重要的是，这些存储在默认目录的页眉/页脚图片不会随着ImageDirPath指定目录的清理而被删除，导致临时文件残留。
技术细节与代码分析
该问题根源于Docx4j内部处理页眉/页脚区域尺寸计算的方式。在进行XSL-FO渲染时，AbstractConversionImageHandler.java负责处理图片存储。当涉及页眉/页脚区域时，Docx4j会使用FopAreeTreeHelper来计算这些区域的大小。FopAreeTreeHelper在内部可能使用了Apache FOP的某些默认设置，而这些设置似乎忽略了外部传入的ImageDirPath配置，导致页眉/页脚中的图片被写入FOP的默认临时目录，通常是/tmp。
以下是转换代码示例，展示了如何设置ImageDirPath并尝试清理：
import org.docx4j.Docx4J;
import org.docx4j.convert.out.FOSettings;
import org.docx4j.convert.out.fo.renderers.FORendererApacheFOP;
import org.docx4j.fonts.Mapper;
import org.docx4j.fonts.BestMatchingMapper;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.apache.fop.apps.FopFactory;
import org.apache.fop.apps.FopFactoryBuilder;
import org.apache.fop.apps.FOUserAgent;
import org.apache.commons.io.FileUtils; // 需要引入Apache Commons IO库
import java.io.File;
import java.io.OutputStream;
public class DocxToPdfConverter {
private static final String TEMP_IMAGE_DIR_PATH = "/tmp/images"; // 自定义临时图片目录
public static void convert(WordprocessingMLPackage wordMLPackage, OutputStream output) throws Exception {
// 1. 设置字体映射
Mapper fontMapper = new BestMatchingMapper();
wordMLPackage.setFontMapper(fontMapper);
// 2. 配置FOSettings
FOSettings foSettings = new FOSettings(wordMLPackage);
foSettings.setApacheFopMime("application/pdf"); // 指定输出MIME类型为PDF
foSettings.setImageDirPath(TEMP_IMAGE_DIR_PATH); // 设置自定义图片临时目录
foSettings.setFoDumpFile(null); // 不生成FO调试文件
// 3. 构建FopFactory和FOUserAgent
FopFactoryBuilder fopFactoryBuilder = FORendererApacheFOP.getFopFactoryBuilder(foSettings);
FopFactory fopFactory = fopFactoryBuilder.build();
FOUserAgent foUserAgent = FORendererApacheFOP.getFOUserAgent(foSettings, fopFactory);
// 4. 执行转换
Docx4J.toFO(foSettings, output, Docx4J.FLAG_EXPORT_PREFER_XSL);
// 5. 清理临时文件
// 清理可能由ObfuscatedFontPart生成的临时字体文件
if (wordMLPackage.getMainDocumentPart().getFontTablePart() != null) {
wordMLPackage.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles();
}
// 6. 释放资源
foSettings = null;
wordMLPackage = null;
// 7. 尝试删除自定义临时图片目录
// 注意：此操作仅删除foSettings.setImageDirPath()指定的目录中的文件
// 无法删除页眉/页脚图片在/tmp中生成的临时文件
try {
File tempImageDir = new File(TEMP_IMAGE_DIR_PATH);
if (tempImageDir.exists() && tempImageDir.isDirectory()) {
FileUtils.deleteDirectory(tempImageDir);
System.out.println("自定义临时图片目录已清理: " + TEMP_IMAGE_DIR_PATH);
}
} catch (Exception e) {
System.err.println("清理自定义临时图片目录失败: " + e.getMessage());
}
}
}在上述代码中，foSettings.setImageDirPath(TEMP_IMAGE_DIR_PATH)旨在将所有临时图片存储到/tmp/images目录，并在转换完成后通过FileUtils.deleteDirectory(new File(TEMP_IMAGE_DIR_PATH))进行清理。然而，实际运行发现，页眉/页脚中的图片仍然会出现在/tmp目录下，且不会被上述清理逻辑删除。
问题根源：Docx4j已知缺陷
根据Docx4j项目维护者的反馈，这确实是Docx4j库的一个已知缺陷（bug）。该问题已被报告并记录在项目的issue跟踪系统中。这意味着它并非由于配置错误或使用不当，而是库本身在处理特定场景（页眉/页脚图片）时的行为不一致性。
当前规避方案
鉴于这是一个已确认的库缺陷，且目前没有直接的API或配置可以解决，唯一的有效规避方案是：
- 避免在Word文档的页眉和页脚中使用图片。
如果文档设计允许，暂时移除页眉/页脚中的图片是目前最直接且无需修改Docx4j源码的解决方案。这可以确保所有临时图片都遵循ImageDirPath的设置，从而能够被程序统一管理和清理。
注意事项与总结
- 临时文件管理： 尽管Docx4j在处理页眉/页脚图片时存在缺陷，导致/tmp目录中可能残留少量图片文件，但通常情况下，这些文件的数量和大小有限，对系统资源的影响较小。然而，在长期运行或高并发的转换服务中，仍需关注/tmp目录的磁盘使用情况。
- 监控与清理： 如果无法避免在页眉/页脚中使用图片，且对/tmp目录的残留文件有严格要求，可能需要考虑在操作系统层面设置定时任务来清理/tmp目录中特定模式（例如，FOP生成的临时文件通常有特定命名规则）的旧文件。但这需要谨慎操作，避免误删其他重要文件。
- 关注官方更新： 作为Docx4j的已知缺陷，未来版本可能会修复此问题。建议持续关注Docx4j的官方发布日志和issue跟踪系统，以便在问题修复后及时升级库版本。
- 替代方案考量： 如果页眉/页脚图片是不可或缺的，且上述规避方案不可接受，可能需要评估其他Word转PDF的库或服务，或者考虑在Word文档生成阶段就避免将图片直接嵌入页眉/页脚，而是通过其他方式（如水印、背景图等）实现类似效果，但这通常会增加文档处理的复杂性。
总而言之，Docx4j在处理页眉/页脚图片时的临时文件残留问题是一个已知缺陷。在官方修复之前，最稳妥的办法是调整文档设计，避免在页眉和页脚中使用图片。
