Tomcat 10部署Spring Boot多模块应用报java.lang.IllegalStateException错误

核心原因 #

Spring Boot 3和Tomcat 10完全基于Jakarta EE 9+（包路径jakarta.*），而Tomcat 9仍使用旧的javax.*规范。你遇到的启动错误，本质是外部Tomcat 10环境下，项目中存在javax.*与jakarta.*的依赖冲突，或者WAR打包/配置不符合Jakarta EE要求——而内嵌Tomcat由Spring Boot统一管理依赖，所以不会出现这类问题。

具体排查与修复步骤 #

1. 清理项目中的javax.*依赖 #

多模块项目很容易在Model/Persistence等模块引入遗留的javax.*依赖，导致Tomcat 10类加载冲突：

• 在项目根目录执行命令：

  mvn dependency:tree
  

  搜索所有包含javax.的依赖，找出非Spring Boot官方管理的旧版本依赖（比如旧版Hibernate、Jackson、JPA API等）。
• 替换为Jakarta EE兼容版本：
  • Hibernate用org.hibernate:hibernate-core:6.x
  • Jackson用com.fasterxml.jackson.core:jackson-databind:2.15.x+
  • 替换javax.persistence-api为jakarta.persistence:jakarta.persistence-api:3.x
• 在Parent POM的<dependencyManagement>中强制统一所有依赖版本，避免子模块私自引入旧版本。

2. 修正WAR打包配置 #

Spring Boot 3部署到外部Tomcat时，必须正确配置打包规则：

• 在Internal（Web）模块的POM中，将内嵌Tomcat标记为provided：

  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId>
      <scope>provided</scope>
  </dependency>
  

• 确保Web模块启动类继承正确的初始化器（注意包路径）：

  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.SpringBootApplication;
  import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
  
  @SpringBootApplication
  public class InternalApplication extends SpringBootServletInitializer {
  
      @Override
      protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
          return application.sources(InternalApplication.class);
      }
  
      public static void main(String[] args) {
          SpringApplication.run(InternalApplication.class, args);
      }
  }
  

• 确认模块打包方式为war：

  <packaging>war</packaging>
  

3. 检查Web配置文件的命名空间 #

如果项目存在web.xml，必须替换为Jakarta EE的命名空间：

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
         version="5.0">
    <!-- 配置内容 -->
</web-app>

同时检查代码中所有导入语句，将javax.servlet、javax.persistence等替换为jakarta.servlet、jakarta.persistence。

4. 验证Tomcat部署权限 #

Tomcat 10对部署目录的权限要求更严格，确保WAR包解压后的目录拥有读写权限，避免因权限不足导致子容器启动失败。

关键结论 #

内嵌Tomcat正常运行说明代码逻辑无问题，问题集中在外部Tomcat环境下的依赖冲突或Jakarta EE配置不兼容。优先排查javax.*依赖的混入，这是最常见的触发原因。

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