Spring MVC + Tomcat 8.5 踩坑实录:Servlet 版本引发的部署失败


🚧 Spring MVC + Tomcat 8.5 踩坑实录:Servlet 版本引发的部署失败

🌐 作者:劲爽小猴头

🗓️ 时间:2025-05-28

📚 关键词:Spring MVC、Tomcat、Servlet、WAR部署、web.xml、Maven、JDK 22


🧩 项目背景

在搭建一个经典的 Spring MVC 项目时,遇到严重的 Tomcat 启动失败问题。环境配置如下:

  • IDEA:2024.1

  • JDK:22

  • Tomcat:8.5.97

  • Spring Framework:5.3.34

  • Servlet API:原来是 4.0.1

  • 打包方式:Maven + WAR


🚨 遇到的错误信息

部署项目到 Tomcat 后,控制台抛出如下错误:

复制代码
Caused by: java.lang.IllegalArgumentException: 找到名为 [spring_web] 的片段。这不是一个合法的名字...

紧接着部署失败,报错信息中还提示:

复制代码
Cannot deploy artifact springmvc-demo:war
Illegal web fragment name

此外,在 web.xml 文件中 IDEA 出现密集报错,例如:

  • Element web-app must be declared

  • Cannot resolve symbol 'servlet-name'

  • Multiple root tags


🔍 问题根因分析

1️⃣ Servlet 版本冲突

  • Tomcat 8.5 的原生支持为 Servlet 3.0/3.1

  • 但项目中引入了 Servlet 4.0.1,导致 web fragment 名称验证失败

2️⃣ web.xml schema 版本不兼容

  • 原来使用的是:

    <web-app version="4.0">
  • IDEA 和 Tomcat 均对这个 schema 支持不佳,IDE 识别失败,Tomcat 启动异常。


🛠️ 解决方案(最终稳定方案)

✅ 一、降级 Servlet API 到 3.0.1

pom.xml 中修改依赖:

复制代码
<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>javax.servlet-api</artifactId>
  <version>3.0.1</version>
  <scope>provided</scope>
</dependency>

⚠️ 注意:scope 必须是 provided,否则会导致 WAR 包重复引入 servlet 相关类。


✅ 二、重写 web.xml 使用 Servlet 3.0 schema

替换为如下配置(位于 src/main/webapp/WEB-INF/web.xml):

复制代码
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                             http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">

    <display-name>Spring MVC Demo</display-name>

    <servlet>
        <servlet-name>dispatcher</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/dispatcher-servlet.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>dispatcher</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

    <!-- 关闭 web-fragment 检查 -->
    <absolute-ordering/>
</web-app>

🧪 重启部署流程

复制代码
mvn clean package

然后重新部署 springmvc-demo.war 到 Tomcat。

如果使用的是 IntelliJ:

  1. Build Artifact → springmvc-demo:war exploded

  2. 在 Run Configuration 中部署该 exploded artifact

  3. 启动 Tomcat


✅ 最终结果

🚀 浏览器访问 http://localhost:8080/springmvc-demo/,看到页面输出:

复制代码
👾 Hello Spring MVC!

✅ 不再出现 IllegalArgumentException

✅ IDEA 中的 web.xml 不再红色报错

✅ Tomcat 启动顺利,部署成功!


📌 总结 & 教训

问题 解决方式
Servlet 版本过高 使用 3.0.1,避免 Tomcat 8.5 不兼容
web.xml 报错 降级 schema 至 3.0
Tomcat 部署失败 关闭 web-fragment 排序

🧠 技术启示:

  • servlet-api 版本要和 Tomcat 版本精确匹配

  • IDEA 对 XML schema 的识别和语义检查十分敏感

  • Spring MVC 老项目依然稳定,但对配置正确性要求更高


🧙 Bonus:下一步可以做什么?

  • ☁️ 升级为 Spring Boot 避免 WAR 配置烦恼

  • 🧪 加入表单登录、拦截器、REST API

  • 🚀 用 Thymeleaf 替代 JSP 以获得更现代的体验


相关推荐
洛可可白23 分钟前
Spring Boot 应用结合 Knife4j 进行 API 分组授权管理配置
java·spring boot·后端
22:30Plane-Moon2 小时前
初识SpringBoot
java·spring boot·后端
黄昏晓x2 小时前
数据结构----排序
java·数据结构·排序算法
97zz2 小时前
项目配置文件正确但是启动失败,报配置文件内容错误或中间件地址与实际不符
java·中间件·springboot
小醉你真好4 小时前
Spring Boot + ShardingSphere 分库分表实战
java·spring boot·后端·mysql
Vdeilae4 小时前
IIS 让asp.net core 项目一直运行
java·服务器·asp.net
YY_TJJ4 小时前
8.4 Java Web(Maven P50-P57)
java·开发语言·maven
cc蒲公英4 小时前
uniapp x swiper/image组件mode=“aspectFit“ 图片有的闪现后黑屏
java·前端·uni-app
刘大辉在路上4 小时前
IntelliJ IDEA开发编辑器摸鱼看股票数据
java·编辑器·intellij-idea
知其然亦知其所以然5 小时前
ChatGPT太贵?教你用Spring AI在本地白嫖聊天模型!
后端·spring·ai编程