Spring Boot应用打war包部署至本地Tomcat后访问返回404错误

出现“Tomcat日志提示war包部署完成，但访问对应路径返回404”的情况，核心逻辑是Spring Web应用的上下文并未完成初始化——Tomcat只是完成了war包的解压动作，没有将应用内的Servlet、Controller路由真正注册到容器中。按实际踩坑概率从高到低，具体诱因有三类：

• 主启动类未适配外置Servlet容器的启动流程
  Spring Boot打war包部署到外置Tomcat时，有个硬性要求：主启动类必须继承SpringBootServletInitializer，重写configure方法，才能让外置Tomcat在加载Web应用的时候触发Spring容器的初始化。如果只保留了默认的main方法写法，没做这个适配，Tomcat解压完war包就结束流程，根本不会启动Spring上下文，所有Controller的路由映射都不会注册，访问任何路径都只会拿到404。
  正确的主启动类参考写法：

@SpringBootApplication
public class DemoSpringWebApplication extends SpringBootServletInitializer {
    public static void main(String[] args) {
        SpringApplication.run(DemoSpringWebApplication.class, args);
    }

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(DemoSpringWebApplication.class);
    }
}

• Tomcat版本和项目的Servlet规范栈不匹配
  当前使用的apache-tomcat-10.0.4版本已经全面切换到Jakarta EE规范，所有Servlet相关API的包名从javax.servlet.*替换为了jakarta.servlet.*。
  如果项目是Spring Boot 2.x及更早版本，这类版本默认依赖javax命名空间的Servlet API，和Tomcat10的规范完全不兼容。这种场景下哪怕日志显示war包部署成功，底层的Servlet初始化会因为包名不匹配静默失败，不会注册任何路由，访问任意路径都返回404。
  解决方式二选一：要么把Tomcat降级到9.x及之前兼容javax栈的版本，要么把项目升级到Spring Boot 3.x（匹配jakarta栈，才能正常在Tomcat10上运行）。
• 内嵌Tomcat依赖的作用域配置错误
  如果pom.xml里引入的spring-boot-starter-tomcat依赖没有指定provided作用域，打出来的war包会内嵌完整的Tomcat运行时类，和外置Tomcat加载的类发生冲突，直接导致Spring上下文初始化中断，最终没有任何接口映射。
  正确的依赖配置片段：

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

快速验证方法 #

• 不要只关注那一行war包部署完成的INFO日志，翻完完整的Tomcat启动日志，查找有没有Spring框架的相关输出：比如有没有Mapped "{[/greeting]}"这类路由注册的日志，有没有Spring容器初始化完成的日志。如果完全没有这类输出，就可以确认是上述配置问题导致Spring上下文根本没启动。
• 可以临时做对照验证：把Tomcat的webapps目录下默认的ROOT目录删掉，把当前的war包改名为ROOT.war放到webapps下，直接访问http://localhost:8080/greeting，如果还是返回404，就可以排除上下文路径配置的问题，确认是应用本身初始化的问题。

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