Maven项目已包含POI类却抛出ClassNotFoundException的原因排查求助

这个问题的核心是POI依赖版本冲突，导致运行时类路径中实际生效的POI版本缺失org.apache.poi.POIXMLTypeLoader类，具体原因和解决办法如下：

1. 版本冲突的本质 #

你的项目声明了POI 4.1.0，但内部依赖Lib-A依赖了另一个版本的POI。Maven的依赖调解机制会根据依赖路径长度或声明顺序选择最终生效的版本：

• 如果Lib-A的POI依赖路径更短，或者在依赖树中先被解析，Maven会优先使用Lib-A依赖的旧版本；
• 而org.apache.poi.POIXMLTypeLoader是POI 4.x版本新增的类（旧版本如3.x中不存在该类），如果最终生效的是旧版本，自然会抛出ClassNotFoundException。

2. 验证冲突 #

执行以下Maven命令查看实际生效的POI版本，确认冲突情况：

mvn dependency:tree -Dverbose -Dincludes=org.apache.poi

若输出结果中POI版本不是4.1.0，说明Lib-A的依赖已覆盖项目声明的版本。

3. 解决办法 #

方法一：锁定POI版本（推荐） #

在项目的pom.xml中通过dependencyManagement强制锁定POI及相关依赖的版本，确保整个依赖树统一使用4.1.0：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi</artifactId>
            <version>4.1.0</version>
        </dependency>
        <dependency>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi-ooxml</artifactId>
            <version>4.1.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

方法二：排除Lib-A中的POI依赖 #

在项目引入Lib-A的依赖时，排除其自带的POI依赖，强制使用项目的4.1.0版本：

<dependency>
    <groupId>your.group.id</groupId>
    <artifactId>Lib-A</artifactId>
    <version>your-lib-version</version>
    <exclusions>
        <exclusion>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi-ooxml</artifactId>
        </exclusion>
    </exclusions>
</dependency>

方法三：升级Lib-A的POI依赖 #

如果有权限修改Lib-A的代码，直接将Lib-A的POI依赖版本升级到4.1.0，从根源解决版本冲突。

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