当前位置：首页 > article >正文

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

article 2025/9/15 9:30:01

🚧 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/javaeehttp://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>