用SpringBoot做过项目的人都知道，执行一下mvn package就能得到一个可执行的jar包，通过java -jar命令就能把服务跑起来，非常方便。但一旦公司要求把应用部署到统一的外部Tomcat集群上，很多人就会发现问题来了：直接把jar包扔进webapps目录根本不起作用，Tomcat完全不认识它。这篇文章就来把这件事讲透，包括jar包和war包在结构上的本质区别、如何改造项目打成war包、部署时的完整流程，以及几个最容易踩的坑。
一、先搞清楚：为什么jar包放不进Tomcat
要理解这个问题，得先看两种包的结构差异。SpringBoot打出来的可执行jar，官方叫fat jar，它的类文件和依赖jar都放在BOOT-INF目录下，入口信息记录在META-INF/MANIFEST.MF里，指向的是SpringBoot自己提供的JarLauncher。这种结构只有SpringBoot的内嵌容器认识，交给java -jar启动时，JarLauncher会先把BOOT-INF下的依赖加载进来，再启动内嵌的Tomcat。
而Tomcat作为Servlet容器，它对应用的识别遵循Servlet规范，要求压缩包是标准的web应用结构：类文件在WEB-INF/classes下，依赖库在WEB-INF/lib下，并且要有合法的部署描述。war包正是这种结构。所以本质上，这不是Tomcat功能不行，而是两种包的目录规范完全对不上，Tomcat拿着fat jar找不到它期望的目录布局，自然就当作普通文件忽略了。
还有一点值得注意：即使你手动把jar后缀改成war，Tomcat依然无法运行它，因为目录结构没有变。正确的做法是让构建工具按war的布局重新打包，同时让SpringBoot的启动逻辑适配Servlet容器的启动方式，这就是下面实例要做的改造。
二、实例演示：把SpringBoot项目改造成war包
假设已经有一个普通的SpringBoot Web项目，用的是spring-boot-starter-web，构建工具为Maven。改造只需要三步，下面逐步演示。
第一步，修改pom.xml。把打包方式改成war，并且把内嵌的Tomcat标记为provided，让它在编译期可用、打包时不带进去，避免和外部Tomcat的容器产生冲突：
<packaging>war</packaging>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<!-- 排除内嵌Tomcat，交由外部容器提供 -->
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<scope>provided</scope>
<!-- 外部Tomcat需要Servlet API支持 -->
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-jasper</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>第二步，改造启动类。原来的启动类只标注了@SpringBootApplication，直接main方法启动。部署到外部Tomcat时，容器是通过Servlet规范来启动应用的，所以需要让启动类继承SpringBootServletInitializer并重写configure方法，把应用入口交给Spring的上下文：
@SpringBootApplication
public class DemoApplication extends SpringBootServletInitializer {
// 支持传统war部署的入口
@Override
protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
return builder.sources(DemoApplication.class);
}
// 本地开发时仍然可以用main方法启动
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}第三步，执行打包命令并在Tomcat中部署。运行mvn clean package，构建成功后在target目录下会看到war包。把它复制到Tomcat的webapps目录下并重命名，比如改成demo.war，启动Tomcat后war包会自动解压出一个demo目录，访问http://localhost:8080/demo/接口路径即可验证。
这里有个细节：war包的文件名会直接影响访问路径的前缀。如果希望不带前缀直接通过根路径访问，可以把war命名为ROOT.war，Tomcat对ROOT应用有特殊处理，会把它当作默认应用。
三、配置调整与常见报错排查
部署到外部Tomcat后，application.properties或application.yml里的一些配置会失效，最典型的就是server.port和server.servlet.context-path。端口由外部Tomcat的server.xml决定，上下文路径默认由war包名决定，写在配置文件里是不会生效的，这点和内嵌容器运行时有明显区别。
再来看几个高频报错。第一个是启动时报类找不到，比如提示Servlet相关的类缺失，多半是忘了把spring-boot-starter-tomcat的scope改成provided，或者直接没有引这个依赖。第二个是Tomcat启动正常但访问404，通常是war包名带来的前缀没加，或者项目里有自定义的WebMvcConfigurer对路径做了额外约束。第三个是日志报端口被占用，说明内嵌Tomcat的依赖没有排除干净，应用在war里又启动了一次内嵌容器，和外部Tomcat抢端口。
最后提一下版本匹配问题。SpringBoot对Servlet容器的版本有要求，比如SpringBoot 3.x系列已经基于Servlet 6.0，需要Tomcat 10.x才能运行，而Tomcat 9及以下用的是javax.servlet包名，两者不兼容。如果你的外部环境是Tomcat 8或9，那么项目应选择SpringBoot 2.x系列，否则部署后大概率直接报类加载异常。打包前确认好容器版本，能省去大量排查时间。
四、部署方式怎么选：内嵌还是外部容器
改造完成后，还需要想清楚这种部署方式是否真的适合你的场景。内嵌容器的方式让应用自带运行环境，一个jar就是一切，天然适合容器化和微服务架构，配合Docker或Kubernetes部署非常顺畅。外部Tomcat的方式则更适合传统企业的运维体系，统一管理端口、连接池、日志和发布流程，运维人员对war包的发布回滚已经很熟悉。
两种方式没有绝对优劣，关键看团队现状。如果只是为了解决单个项目的部署问题，改成war包即可；如果公司正在向云原生迁移，建议保留jar包的运行方式，通过标准化的发布平台来管理。无论选择哪种，理解jar和war在结构层面的差异，以及SpringBoot对两种启动方式的不同适配逻辑，都能让你在遇到部署问题时快速定位原因，而不是盲目地改配置碰运气。
SpringBoot打包Tomcat部署war包修改时间：2026-09-05 10:04:38