XDocReport生成docx文档报错：“Word尝试打开文件时遇到错误”求助

阿华AIGC实验室

2026-4-30

我之前也碰到过类似的问题，结合XDocReport 2.0.2的特性和Office 2016的兼容性，给你几个排查方向和解决办法：

1. 先检查docx模板的合法性

确保你的模板是用Office 2016直接创建/保存的，尽量避免用WPS等其他工具修改，这类工具可能会生成Word不兼容的XML节点。

核对模板里的Freemarker循环标签是否正确嵌套在表格行内，比如正确的写法应该是：

[#list dataList as item]
<w:tr>
  <w:td><w:t>${item.column1}</w:t></w:td>
  <w:td><w:t>${item.column2}</w:t></w:td>
</w:tr>
[/#list]

可以把docx后缀改成zip，解压后打开word/document.xml文件，检查有没有未闭合的XML标签或者语法错误——这是生成损坏文档的常见原因。

2. 检查代码中的输出流处理

务必确保输出流被正确关闭和刷新，未关闭的流会导致文件不完整，Word自然无法打开：

FileOutputStream out = new FileOutputStream("result.docx");
report.process(context, out);
out.flush(); // 先刷新缓冲区
out.close(); // 必须关闭流

如果是在Web场景下输出到浏览器，要设置正确的响应头，避免MIME类型错误：

response.setContentType("application/vnd.openxmlformats-officedocument.wordprocessingml.document");
response.setHeader("Content-Disposition", "attachment; filename=report.docx");

3. 排查依赖版本兼容性

XDocReport 2.0.2对Freemarker的版本有要求，建议搭配2.3.30版本的Freemarker，过高或过低都可能出现隐性的兼容性问题。如果用Maven，依赖配置应该是：

<dependency>
  <groupId>org.freemarker</groupId>
  <artifactId>freemarker</artifactId>
  <version>2.3.30</version>
</dependency>
<dependency>
  <groupId>fr.opensagres.xdocreport</groupId>
  <artifactId>fr.opensagres.xdocreport.template.freemarker</artifactId>
  <version>2.0.2</version>
</dependency>

避免手动引入与XDocReport内置版本冲突的POI包，XDocReport内部依赖POI，强行替换版本会导致文档生成异常。

4. 用最小化示例测试

先写一个极简的测试代码，排除业务逻辑的干扰：

// 加载模板
InputStream templateIn = new FileInputStream("simple_template.docx");
IXDocReport report = XDocReportRegistry.getRegistry().loadReport(templateIn, TemplateEngineKind.Freemarker);

// 构造测试数据
IContext context = report.createContext();
List<Map<String, String>> testData = new ArrayList<>();
Map<String, String> row = new HashMap<>();
row.put("name", "测试项");
row.put("value", "测试值");
testData.add(row);
context.put("dataList", testData);

// 生成文档
FileOutputStream out = new FileOutputStream("test_result.docx");
report.process(context, out);

// 关闭流
out.close();
templateIn.close();