Spring Boot部署JBoss WildFly遇IncompatibleClassChangeError求助

错误根源 #

这个错误是由于Servlet API类冲突导致的：你的项目打包时带入了Tomcat相关的Servlet实现类，而WildFly自身已经提供了一套Servlet容器（Undertow）及对应的API类，两者的HttpServlet类及其内部类加载自不同来源，引发类结构不兼容。

具体修复步骤 #

1. 调整Gradle依赖配置 #

修改build.gradle，移除冲突的Servlet相关依赖，让WildFly提供容器支持：

• 排除Spring Boot Web Starter中的Tomcat依赖：

implementation('org.springframework.boot:spring-boot-starter-web') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
}

• 移除手动添加的javax.servlet-api依赖（WildFly的javax.servlet.api模块已提供该API）：
  删除这一行：

providedRuntime 'javax.servlet:javax.servlet-api:3.1.0'

• 将Tomcat Jasper依赖改为providedRuntime（避免打包进war，使用WildFly自带的JSP处理能力）：

providedRuntime "org.apache.tomcat.embed:tomcat-embed-jasper"

2. 优化jboss-deployment-structure.xml #

确保配置正确排除项目中的Servlet相关模块，并优先使用WildFly自带的API：

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <dependencies>
            <module name="javax.servlet.api" export="true"/>
            <module name="javax.servlet.jsp.api" export="true"/>
        </dependencies>
        <exclude-subsystems>
            <subsystem name="logging" />
            <subsystem name="jaxrs" />
            <subsystem name="resteasy" />
        </exclude-subsystems>
        <exclusions>
            <!-- 保留原有排除项并添加Tomcat Jasper排除 -->
            <module name="org.slf4j" />
            <module name="org.slf4j.impl" />
            <module name="org.slf4j.jcl-over-slf4j"/>
            <module name="org.apache.commons.logging"/>
            <module name="tomcat-embed-core"/>
            <module name="tomcat-embed-jasper"/>
            <module name="org.apache.juli"/>
            <module name="org.apache.juli.logging"/>
            <module name="org.apache.juli.logging.LogFactory"/>
            <module name="org.apache.log4j"/>
            <module name="javaee.api" />
            <module name="javax.xml.bind.api" />
            <module name="com.fasterxml.jackson.core.jackson-core" />
            <module name="com.fasterxml.jackson.core.jackson-databind" />
            <module name="com.fasterxml.jackson.core.jackson-annotations" />
            <module name="com.fasterxml.jackson.jaxrs.jackson-jaxrs-json-provider" />
            <module name="org.jboss.resteasy.resteasy-jaxb-provider" />
            <module name="org.jboss.resteasy.resteasy-jettison-provider"/>
            <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
            <module name="org.jboss.resteasy.resteasy-jackson2-provider" />
        </exclusions>
    </deployment>
</jboss-deployment-structure>

3. 验证打包结果 #

执行gradle clean war后，检查生成的war包的WEB-INF/lib目录，确保没有以下文件：

• tomcat-embed-core-*.jar
• tomcat-embed-jasper-*.jar
• javax.servlet-api-3.1.0.jar

如果这些文件存在，说明依赖排除不彻底，需要重新检查Gradle配置。

原理说明 #

通过排除Spring Boot自带的Tomcat容器依赖，让WildFly作为Servlet容器提供运行时环境；同时确保项目不打包Servlet API类，直接使用WildFly自带的javax.servlet.api模块，避免同一个类被多个类加载器加载，从而解决IncompatibleClassChangeError。

内容的提问来源于stack exchange，提问作者CHO HYEON SOO