POI-TL 不能直接读取 Word 内容，它仅支持填充含占位符的 .docx 模板；读取原文本、表格等需用 Apache POI 的 XWPFDocument。
POI-TL 能直接读取 Word 内容吗？不能
POI-TL 是个模板引擎，核心职责是「填充」，不是「解析」。它不提供 DocumentReader 或类似接口；你传给它的必须是已定义好占位符（如 {{name}}）的 .docx 模板文件，然后靠 DocxRenderData 注入数据生成新文档。想提取原文本、表格、图片或样式？得换工具——比如 Apache POI 的 XWPFDocument。
用 Apache POI 读取 .docx 文本内容的最小可行路径
真正读 Word 的活儿，交给 XWPFDocument 更靠谱。注意它只支持 .docx（Office 2007+），不支持老式 .doc。
常见错误现象：InvalidFormatException: Package should contain a content type part [M1.13] —— 多半是传了空文件、损坏文件，或误用了 .doc 文件。
- 确保依赖含
org.apache.poi:poi-ooxml（别漏掉ooxml-schemas或用新版自动传递） - 用
FileInputStream或OPCPackage.open()打开，别用new XWPFDocument()空构造器去“读” - 段落文本用
paragraph.getText()，但注意它不包含换行符和制表符；需要结构化提取时，得遍历paragraph.getRuns() - 表格内容要嵌套两层循环：
document.getTables()→table.getRows()→row.getTableCells()
try (XWPFDocument doc = new XWPFDocument(new FileInputStream("demo.docx"))) {
for (XWPFParagraph p : doc.getParagraphs()) {
System.out.println(p.getText()); // 纯文本，无格式
}
}
POI-TL 填充模板时，为什么变量不生效？
不是语法写错，就是上下文没对上。POI-TL 默认用 {{key}}，但如果你改过 Configure 的 symbol，或用了 TagRenderPolicy 自定义逻辑，就容易失配。
立即学习“Java免费学习笔记（深入）”；
- 模板里写的是
{{user.name}}，但传的RenderData是Map<String, Object>且 key 是"name"→ 不会匹配，得用DocxRenderData.of(map)或改模板为{{name}} - 用了
LoopRenderData但模板中漏了#for标签，或写成#foreach（POI-TL 只认#for） - 图片占位符
{{image:logo}}对应的ImageRenderData路径不对，或图片流已关闭 —— 它要求输入流可重复读，FileInputStream行，ByteArrayInputStream也行，但网络流或一次性的ServletInputStream就会失败
导出大文档卡顿或内存溢出怎么办？
POI-TL 底层还是 Apache POI，而 XWPFDocument 是 DOM 模式加载，整份文档进内存。万一段落超 5000 行、表格嵌套深、图片多，很容易 OOM。
- 避免在模板里塞「假数据占位」再运行时全删——先清理模板冗余内容
- 图片尽量用
ImageRenderData的byte[]构造，别传File路径让 POI-TL 自己读，减少 IO 和流管理开销 - 真要处理超大文档，得绕过 POI-TL，用
StreamingProblem思路：用XmlStreamWriter直接写 OOXML 结构，但这就脱离模板引擎范畴了 - JVM 参数调
-Xmx2g是权宜之计，本质问题在模型设计——是否真需要单次导出 100 页 Word？考虑分页 PDF 或流式 CSV 更实际
模板引擎省事，但别把它当万能解析器；读和写是两件事，混用只会让异常堆栈更难读。
