IntelliJ项目本地运行正常 war包部署Tomcat无法访问Servlet

核心差异本质 #

IDEA启动关联的本地Tomcat时，不会直接使用你手动构建的war包，也不会完全使用Tomcat原生的部署扫描逻辑，两者的运行时环境、配置加载逻辑存在本质区别，和web.xml里有没有写映射没有直接关系。

1. IDEA内置运行模式的特殊处理逻辑 #

从Servlet 3.0规范开始，已经不需要在web.xml中手动编写Servlet映射，类上标注的@WebServlet注解就可以完成映射注册，IDEA运行时会做两层额外保障，哪怕配置有小瑕疵也能正常访问：

• IDEA会在自身缓存目录生成一份独立的Tomcat运行副本，不会修改你本地安装的Tomcat原生配置。启动前它会自动扫描项目中所有带@WebServlet、@WebFilter、@WebListener注解的类，直接把映射规则注入到运行时的部署配置中，跳过Tomcat原生的注解扫描流程。
• IDEA采用爆炸式热部署模式运行项目，直接把编译后的target/classes目录、依赖jar包挂载到Tomcat的资源路径下，不会走完整的war包打包、解压、校验流程，很多打包阶段才会暴露的配置缺失、文件遗漏问题，在IDEA直接运行时完全不会触发。

2. 独立Tomcat部署war包失败的常见原因 #

手动把war包丢到webapps目录部署时，Tomcat会严格按照Servlet规范走完整的包校验、类扫描、注册流程，以下几种问题都会导致Servlet无法访问：

• 规范版本不兼容：如果你用的是Tomcat 10以下版本，项目却引入了Jakarta EE 9+的jakarta.servlet.*依赖，或者反过来Tomcat 10+部署了用旧版javax.servlet.*编写的Servlet，Tomcat根本识别不到类上的注解，完成不了注册。
• 打包产物不规范：手动打包时遗漏了WEB-INF/classes下的编译类文件、没有生成符合规范的META-INF元数据目录，或者web.xml声明的Servlet版本低于3.0（比如用了2.5版本的DTD声明），Tomcat默认不会开启注解扫描，只会读取web.xml里显式配置的映射。
• 上下文路径不匹配：IDEA运行时通常会把项目上下文路径设为/，直接通过/hello-servlet就能访问；但独立部署时，war包的文件名就是默认上下文路径，比如war包叫demo.war，正确访问路径应该是/demo/hello-servlet，漏写上下文前缀会直接404。
• 文件权限异常：Tomcat进程没有war包解压目录的读取权限，加载不到Servlet类文件，自然无法完成注册。

3. 快速排查修复步骤 #

• 优先用构建工具（Maven/Gradle）的官方war插件打包，不要手动压缩编译产物：Maven项目配置maven-war-plugin，执行mvn clean package生成标准结构的war包，打包前确认Servlet依赖的scope为provided，避免和Tomcat自带的Servlet包冲突。
• 核对Tomcat版本和项目依赖的匹配关系：Tomcat 9及以下适配Java EE（包名前缀javax.*），Tomcat 10及以上适配Jakarta EE（包名前缀jakarta.*）。
• 检查web.xml的版本声明，确保版本≥3.0，最简配置参考：

<?xml version="1.0" encoding="UTF-8"?>
<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_6_0.xsd"
         version="6.0">
</web-app>

• 部署后查看Tomcat的logs/catalina.out启动日志，确认是否有对应Servlet的注册成功日志，同时核对访问路径是否带上了war包对应的上下文前缀。

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