POI 5.2.4+（推荐5.2.5）适配JDK 17+，需用poi-ooxml或poi-ooxml-lite并排除旧版xmlbeans；XWPFDocument空参构造易NPE，应传空白模板流；中文需setWordFont并配字体文件；大文档须流式写入、禁用样式缓存、避免复用实例。
Apache POI 用哪个版本才不和 JDK 冲突
Java 17+ 项目里直接加 poi-3.17 或更老的版本，十有八九会报 NoClassDefFoundError: org/apache/xmlbeans/XmlObject 或 java.lang.NoSuchMethodError —— 不是代码写错了，是底层依赖链断了。
POI 5.x 起强制要求 JDK 8+，但真正稳住 JDK 17 的是 poi-5.2.4 及之后版本（推荐 poi-5.2.5），且必须配套使用 poi-ooxml-lite 或完整版 poi-ooxml，不能只引 poi 核心包。
-
poi：只处理 .xls（Excel 97–2003），不支持 Word - 导出 Word 必须用
poi-ooxml（含XWPFDocument） - 若只生成简单文档、想减小体积，可用
poi-ooxml-lite+xmlbeans手动排除冲突模块 - Maven 中显式排除
xmlbeans旧版（如org.apache.xmlbeans:xmlbeans:2.6.0），改用5.1.1+
为什么 new XWPFDocument() 就抛 NullPointerException
不是对象没初始化，而是底层 XML 解析器找不到默认资源。常见于 Spring Boot 项目打包成 jar 后运行时，new XWPFDocument() 报 NullPointerException 在构造器内部，根源是 OOXMLLite 模式下缺失 content-types.xml 模板。
最简解法：别空参构造，改用带 InputStream 的构造函数，哪怕传个空模板流：
立即学习“Java免费学习笔记（深入）”；
try (InputStream is = new ByteArrayInputStream(new byte[0]);
XWPFDocument doc = new XWPFDocument(is)) {
// 后续写入
}
更稳妥的做法是准备一个最小空白 .docx（用 Word 另存为“Word 文档”即可，约 4KB），放在 src/main/resources/templates/blank.docx，然后：
try (InputStream is = getClass().getResourceAsStream("/templates/blank.docx");
XWPFDocument doc = new XWPFDocument(is)) { ... }
中文段落乱码或字体不生效
POI 默认不嵌入中文字体，XWPFRun.setFontFamily("微软雅黑") 看似调用了，但 Windows / Linux / macOS 渲染结果天差地别——Linux 服务器上基本显示为空方块或宋体 fallback。
- 必须同时设置中文字体 + 字符集：
run.setFontFamily("微软雅黑"); run.setBold(true); run.setFontSize(12); - 关键一步：在
XWPFParagraph上设置语言属性：paragraph.setWordFont("微软雅黑");（注意不是setFontFamily） - 如果目标环境无该字体，可降级用
"SimSun"（宋体）或"Noto Sans CJK SC"（需提前部署字体文件） - 避免用
setBold(true)单独加粗，应配合字体设置一起调用，否则部分 Office 版本忽略加粗样式
导出大文档卡死或 OOM
一次性往 XWPFDocument 里塞几百段落、上千表格行，很容易触发 GC 频繁甚至 OutOfMemoryError: Java heap space —— POI 的 DOM 模式把整个文档树全载内存里。
真实业务中，能流式写就别 DOM 写：
- 用
XWPFDocument.write(OutputStream)直接刷出，别先转byte[] - 超大表格改用
XWPFTable+addRow()分批构建，别一口气createTable(rows, cols) - 禁用自动样式缓存：
document.getStyles().setStyleCacheEnabled(false) - 导出完立刻
document.close()，否则ZipPackage底层资源不释放
真要处理万行级文档，建议切分逻辑段落，或换用 docx4j 的 SAX 模式，POI 的设计定位本就不是超大数据量导出。
最容易被忽略的是：XWPFDocument 实例不能复用。每次导出都得新建，它不是线程安全的，也不是轻量对象。
