EasyPoi导出Word时模板变量不生效？

Question

EasyPoi导出Word时模板变量不生效，是高频踩坑问题。常见原因包括：① Word模板未使用正确语法（如`{{name}}`而非`${name}`或`@name@`）；② 模板中变量所在段落被隐藏、分节符干扰或含不可见格式符号（如零宽空格），导致EasyPoi解析失败；③ 实体类字段名与模板变量名大小写/下划线不一致（如Java字段`userName`对应模板`{{username}}`，因默认开启`ignoreCase=false`而匹配失败）；④ 未启用`@ExcelTarget`注解或`@Excel`注解缺失，导致字段未被识别为导出属性；⑤ 使用了不支持的复杂结构（如嵌套对象未加`@ExcelEntity`，或List集合未用`@ExcelCollection`标注）。建议统一使用`{{xxx}}`语法，校验字段命名一致性，开启`ignoreCase=true`，并用EasyPoi官方模板校验工具预检。

Answer 1

```html

一、现象层：模板变量“消失”——你看到的只是表象

导出Word后，本该显示{{userName}}的位置一片空白，或原样输出{{userName}}字符串；控制台无报错，日志仅提示“模板解析完成”。这是最典型的“变量不生效”表层现象。它不触发异常，却让业务交付卡在最后一公里——用户收到的是“骨架文档”，而非可用报告。

二、语法层：模板引擎的“语言契约”必须严格遵守

• ✅ 正确语法：{{userName}}（双大括号+HTML注释包裹，支持驼峰/下划线自动映射）
• ❌ 常见误用：${userName}（EL表达式，EasyPoi Word不识别）、@userName@（旧版POIUtils遗留写法）、[[userName]]（非标准扩展）
• ⚠️ 特别注意：Word中手动输入时，{与之间**不能有空格**，否则解析器视为普通文本

三、文档结构层：Word不是纯文本，而是格式化容器

EasyPoi通过Apache POI读取Word的XML结构（.docx本质是ZIP包内含word/document.xml）。以下结构问题将导致变量被跳过：

问题类型	检测方式	修复建议
段落隐藏（字体颜色=白色/字号=1）	选中段落 → 右键【字体】→ 检查颜色/字号	清除所有隐藏格式，使用【开始】→【清除所有格式】
零宽空格（U+200B）、零宽断字符（U+200C）	复制变量文本到Notepad++ → 编码→转为ANSI → 查看十六进制	重输变量，或用正则\u200b|\u200c|\u200d全局替换

四、映射层：Java对象与模板的“契约一致性”

EasyPoi默认关闭忽略大小写（ignoreCase = false），这意味着：

// 实体类字段
private String userName; // 驼峰命名

// 模板中必须严格匹配：
{{userName}} ✅  
{{username}} ❌（小写u，匹配失败）
{{USER_NAME}} ❌（全大写下划线，不触发自动转换）

解决方案：在导出调用处显式开启忽略大小写：

WordExportParams params = new WordExportParams();
params.setIgnoreCase(true); // 关键！覆盖默认false
WordExportUtil.exportWord07(templatePath, data, params);

五、注解层：元数据驱动的“导出可见性”控制

EasyPoi采用注解驱动模型，未标注即不可见：

• @ExcelTarget：必须标注在实体类上，声明该类用于EasyPoi导出（否则整个类被忽略）
• @Excel：标注在字段上，即使字段名与模板一致，缺失此注解仍不会注入值
• 嵌套对象需@ExcelEntity，集合需@ExcelCollection，否则EasyPoi视其为普通Object，不递归解析

六、验证层：从“人肉排查”到“机器预检”的范式升级

graph TD
  A[编写Word模板] --> B{是否通过官方校验工具？}
  B -->|否| C[自动定位：语法错误/非法字符/结构异常]
  B -->|是| D[执行Java导出逻辑]
  C --> E[修正模板并重试]
  D --> F[比对：模板变量 vs 实体字段 vs 注解配置]

七、工程实践：五步标准化检查清单

1. ✅ 使用{{xxx}}统一语法，禁用任何其他占位符变体
2. ✅ 用Notepad++或VS Code Hex Editor检查模板文件是否存在不可见Unicode字符
3. ✅ 实体类添加@ExcelTarget，所有待导出字段标注@Excel
4. ✅ 导出参数强制设置params.setIgnoreCase(true)
5. ✅ 运行EasyPoiTemplateChecker（官方CLI工具）生成结构报告

八、高阶避坑：被低估的“分节符”与“样式继承”陷阱

当模板含分节符（Section Break）时，EasyPoi可能将后续段落解析为新节上下文，导致变量绑定失效；若变量所在段落应用了自定义样式（如“标题1”），而该样式链接到多级列表，其内部XML可能包裹额外w:pPr节点，干扰占位符提取。推荐做法：在Word中【设计】→【段落】→ 清除所有多级列表，将样式重置为“正文”。

九、调试技巧：让EasyPoi“开口说话”

启用DEBUG日志级别，重点关注：

org.jeecgframework.poi.word.PoiWordExport —— 模板加载路径与XML解析摘要

org.jeecgframework.poi.word.parse.WordParseUtil —— 变量提取数量与字段映射日志

若日志中出现find 0 variables in paragraph，立即检查该段落是否被隐藏或含零宽字符。

十、终极建议：建立团队级EasyPoi Word模板规范

制定《EasyPoi Word模板开发SOP》，强制要求：

• 模板必须基于官方示例.docx衍生（避免格式污染）
• 所有变量用{{xxx}}且置于独立段落（禁用表格内嵌变量）
• CI流程集成poi-template-validator Maven插件，编译前校验模板
• 新人入职必过“EasyPoi Word Debug Lab”实战考核（含5个预设故障模板）

```