Spring Boot 3.1部署本地Tomcat失败，请求技术排查

问题描述 #

我是后端开发新手，开发了一个简单WebHook接收应用。本地Spring Boot启动的localhost:8080上用Postman测试正常，但打包成.war部署到Tomcat 9.0.78后无法运行。执行./mvn clean package打包时，终端提示：

Plugin validation issues were detected in 1 plugin(s)

• org.apache.maven.plugins:maven-war-plugin:3.2.2

Tomcat版本为9.0.78，application.properties为空，相关代码如下：

pom.xml #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <parent>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-parent</artifactId>
       <version>3.1.1</version>
       <relativePath/> <!-- lookup parent from repository -->
   </parent>
   <groupId>test.gio</groupId>
   <artifactId>TestFinal</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <packaging>war</packaging>
   <name>TestFinal</name>
   <description>Demo project for webhook</description>
   <properties>
       <java.version>17</java.version>
   </properties>
   <dependencies>
       <dependency>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-tomcat</artifactId>
           <scope>provided</scope>
       </dependency>
       <dependency>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-data-jpa</artifactId>
       </dependency>
       <dependency>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-web</artifactId>
       </dependency>
       <dependency>
           <groupId>com.h2database</groupId>
           <artifactId>h2</artifactId>
           <scope>runtime</scope>
       </dependency>
        <dependency>
           <groupId>org.apache.tomcat.embed</groupId>
           <artifactId>tomcat-embed-jasper</artifactId>
           <scope>provided</scope>
           <version>9.0.75</version>
       </dependency>

       <dependency>
           <groupId>org.projectlombok</groupId>
           <artifactId>lombok</artifactId>
           <optional>true</optional>
       </dependency>
       <dependency>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-test</artifactId>
           <scope>test</scope>
       </dependency>
       <dependency>
           <groupId>com.fasterxml.jackson.core</groupId>
           <artifactId>jackson-databind</artifactId>
           <version>2.15.2</version>
       </dependency>
   </dependencies>

   <build>
       <finalName>TestFinal</finalName>
       <plugins>
           <plugin>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-maven-plugin</artifactId>
               <configuration>
                   <excludes>
                       <exclude>
                           <groupId>org.projectlombok</groupId>
                           <artifactId>lombok</artifactId>
                       </exclude>
                   </excludes>
               </configuration>
           </plugin>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-war-plugin</artifactId>
               <version>3.2.2</version>
               <configuration>
                   <failOnMissingWebXml>false</failOnMissingWebXml>
               </configuration>
           </plugin>
       </plugins>
   </build>

</project>

controller.java #

@RestController
public class WebHookController {

    @PostMapping("/webhook")
    public ResponseEntity<String> webhook(@RequestBody OrderPayload orderPayload) {
        System.out.println("Webhook received!");
        orderPayloadService.processOrderPayload(orderPayload);
        return ResponseEntity.ok("Webhook received! Sei un grande :)");
    }

  @GetMapping("/hello")
    public String hello()
    {
        return "Hello User, have a nice day.";
    }
}

Application.java #

@SpringBootApplication
public class TestFinalApplication extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application)
    {
        return application.sources(TestFinalApplication.class);
    }
    @RequestMapping("/TestFinal")
    public static void main(String[] args) {
        SpringApplication.run(TestFinalApplication.class, args);
    }

}

ServletInitializer.java #

public class ServletInitializer extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(TestFinalApplication.class);
    }

}

核心问题与修复方案 #

1. Spring Boot与Tomcat版本不兼容 #

Spring Boot 3.1.1依赖Servlet 6.0规范，但Tomcat 9.0.x仅支持到Servlet 4.0，这是部署失败的核心原因。

• 修复：将Spring Boot版本降级到2.7.x系列（兼容Tomcat 9），或升级Tomcat到10.x+（支持Servlet 6.0）。推荐降级Spring Boot，Tomcat 9是企业级稳定版本。

2. 重复的ServletInitializer类 #

Application.java已经继承SpringBootServletInitializer并实现了configure方法，单独的ServletInitializer.java会导致容器初始化冲突。

• 修复：删除单独的ServletInitializer.java文件。

3. maven-war-plugin版本过低 #

3.2.2版本的maven-war-plugin与Spring Boot 3.x不兼容，导致插件验证警告。

• 修复：如果降级到Spring Boot 2.7.x，可升级插件到3.3.2+；如果保留Spring Boot 3.x，需升级到3.4.0+版本。

4. 冗余依赖与版本冲突 #

• 手动添加的tomcat-embed-jasper和jackson-databind依赖会与Spring Boot父项目管理的版本冲突，且tomcat-embed-jasper在War部署场景下无需手动指定。
• 修复：移除这两个手动添加的依赖，由Spring Boot自动管理适配版本。

5. Application类注解错误 #

main方法上的@RequestMapping("/TestFinal")无意义，属于错误用法。

• 修复：删除该注解。

修改后的关键代码示例 #

修改后的pom.xml（降级到Spring Boot 2.7.17） #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.17</version>
        <relativePath/>
    </parent>
    <groupId>test.gio</groupId>
    <artifactId>TestFinal</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>war</packaging>
    <name>TestFinal</name>
    <description>Demo project for webhook</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>TestFinal</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

修改后的Application.java #

@SpringBootApplication
public class TestFinalApplication extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application)
    {
        return application.sources(TestFinalApplication.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(TestFinalApplication.class, args);
    }
}

部署验证步骤 #

1. 执行mvn clean package重新打包，确保target目录生成正确的war文件。
2. 将war文件放入Tomcat的webapps目录，启动Tomcat。
3. 访问测试路径：http://<Tomcat地址>:<端口>/TestFinal/hello，若返回"Hello User, have a nice day."则部署成功。
4. 若仍有问题，查看Tomcatlogs目录下的catalina.out或localhost.log，定位具体启动错误。

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