Java用POI实现Word导出基础教程

本文深入解析了在Java 17+环境下使用Apache POI安全、高效导出Word文档的核心实践，直击开发者高频踩坑点：明确推荐POI 5.2.4+（首选5.2.5）配合poi-ooxml-lite或poi-ooxml，并彻底排除旧版xmlbeans以规避JDK兼容性崩溃；破解XWPFDocument空构造引发的NPE陷阱，强调必须基于空白模板流初始化；详解中文渲染失效根源——需协同设置XWPFRun字体族与XWPFParagraph的setWordFont，而非仅调用setFontFamily；并给出大文档导出的性能救命指南：强制流式写入、禁用样式缓存、杜绝实例复用、及时关闭资源，避免OOM与卡死。每一条都是生产环境血泪经验凝练，助你绕过POI“看似简单、实则深坑”的所有暗礁。

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 的构造函数，哪怕传个空模板流：

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 实例不能复用。每次导出都得新建，它不是线程安全的，也不是轻量对象。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。