Apache POI 5.0生产环境读取Excel工作表名称返回null问题问询

已知触发原因 #

• 依赖版本不一致：项目中同时引入的poi、poi-ooxml以及相关附属依赖版本不匹配，是该问题最高发的诱因。本地开发环境因依赖加载顺序、仲裁规则的差异，刚好匹配到一致版本可正常运行，生产环境依赖加载优先级不同就会出现能识别sheet数量、但无法读取sheet名称的问题。
• 缺少OOXML解析依赖：POI 5.0版本后对OOXML格式的解析依赖做了拆分，核心包不包含完整的schema定义，如果未引入poi-ooxml-lite或poi-ooxml-full依赖，就会导致sheet元数据解析失败，名称字段返回null。
• XML解析器冲突：生产环境应用服务器（如Tomcat、WebLogic）自带的XML解析器与POI依赖的xmlbeans解析逻辑不兼容，会导致sheet名称对应的XML节点读取失败。

排查解决步骤 #

1. 校验依赖版本一致性
   Maven项目执行以下命令打印依赖树：
   mvn dependency:tree | grep poi
   Gradle项目执行：
   gradlew dependencies | grep poi
   检查所有poi相关依赖的版本是否完全一致，若存在低版本冲突，使用exclusion标签排除第三方包引入的不一致版本POI依赖，保证poi、poi-ooxml、poi-ooxml-lite/poi-ooxml-full版本均为5.0.0。

2. 补充完整OOXML依赖
   在项目依赖中添加对应版本的poi-ooxml-full依赖，覆盖默认的轻量schema包，避免解析规则缺失。

3. 强制指定XML解析器
   在应用启动参数中添加以下配置，优先使用JDK自带的XML解析器，避免服务器自带解析器的兼容性问题：
   -Djavax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl

4. 版本升级
   上述步骤都无法解决时，可将POI整体升级至5.2.3及以上稳定版本，该版本已修复多个sheet名称解析的已知bug。

内容的提问来源于stack exchange，提问作者fraserh