Spring MVC请求映射失效求助：Tomcat+Thymeleaf环境问题排查

核心问题根源梳理 #

你遇到的所有问题本质上是版本不兼容+核心配置错误导致的：

• 请求映射失效、断点不触发：Spring容器未正确加载Controller，或DispatcherServlet配置错误
• Thymeleaf模板404但JSP正常：模板路径配置错误，或Thymeleaf未集成生效
• 各类异常（ClassCastException/NoSuchMethodError/BeanCreationException）：完全是Spring、Thymeleaf、Tomcat三者的版本不匹配导致

第一步：锁定兼容的版本组合（必须严格对应） #

这是解决所有异常的前提，禁止跨版本混用javax.servlet和jakarta.servlet体系：

组合1：Tomcat9 + JDK8/11 + Spring5 + Thymeleaf3 #

Tomcat9基于javax.servlet规范，对应Spring5（最后一个支持javax的版本）和Thymeleaf3（适配Spring5）：

<!-- pom.xml核心依赖 -->
<dependencies>
    <!-- Spring MVC -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>5.3.30</version> <!-- 稳定版 -->
    </dependency>
    <!-- Thymeleaf Spring5集成包 -->
    <dependency>
        <groupId>org.thymeleaf</groupId>
        <artifactId>thymeleaf-spring5</artifactId>
        <version>3.1.2.RELEASE</version>
    </dependency>
    <!-- Servlet API（Tomcat已提供，标记为provided） -->
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>4.0.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

组合2：Tomcat10+ + JDK17+ + Spring6 + Thymeleaf6 #

Tomcat10+切换为jakarta.servlet规范，必须搭配Spring6和Thymeleaf6：

<!-- pom.xml核心依赖 -->
<dependencies>
    <!-- Spring MVC -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>6.1.5</version> <!-- 稳定版 -->
    </dependency>
    <!-- Thymeleaf Spring6集成包 -->
    <dependency>
        <groupId>org.thymeleaf</groupId>
        <artifactId>thymeleaf-spring6</artifactId>
        <version>6.1.2.RELEASE</version>
    </dependency>
    <!-- Servlet API（Tomcat已提供，标记为provided） -->
    <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>6.0.0</version> <!-- Tomcat11对应6.0，Tomcat10对应5.0 -->
        <scope>provided</scope>
    </dependency>
</dependencies>

第二步：修复核心配置错误 #

1. 确保Spring容器加载Controller #

• 配置类必须添加@EnableWebMvc和@ComponentScan，指定你的Controller所在包：

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.yourpackage.controller") // 替换成你的包路径
public class WebConfig implements WebMvcConfigurer {
    // 后续Thymeleaf配置写在这里
}

• Controller类必须加@Controller注解，方法加@RequestMapping：

@Controller
public class HelloController {
    @RequestMapping("/helloW")
    public String hello() {
        return "hello"; // 对应templates/hello.html
    }
}

2. 正确配置Thymeleaf视图解析器 #

在WebConfig中添加Thymeleaf相关Bean，指定模板路径为classpath:/templates/（这是Thymeleaf默认的模板根目录，必须把.html文件放在这里）：

@Bean
public SpringResourceTemplateResolver templateResolver() {
    SpringResourceTemplateResolver resolver = new SpringResourceTemplateResolver();
    resolver.setPrefix("classpath:/templates/");
    resolver.setSuffix(".html");
    resolver.setTemplateMode(TemplateMode.HTML);
    resolver.setCharacterEncoding("UTF-8");
    return resolver;
}

@Bean
public SpringTemplateEngine templateEngine() {
    SpringTemplateEngine engine = new SpringTemplateEngine();
    engine.setTemplateResolver(templateResolver());
    engine.setEnableSpringELCompiler(true);
    return engine;
}

@Override
public void configureViewResolvers(ViewResolverRegistry registry) {
    ThymeleafViewResolver viewResolver = new ThymeleafViewResolver();
    viewResolver.setTemplateEngine(templateEngine());
    viewResolver.setCharacterEncoding("UTF-8");
    registry.viewResolver(viewResolver);
}

3. 正确配置DispatcherServlet #

确保DispatcherServlet映射到/（不要用/*，会覆盖静态资源访问）：

方式1：JavaConfig（推荐）

public class WebAppInitializer implements WebApplicationInitializer {
    @Override
    public void onStartup(ServletContext servletContext) throws ServletException {
        AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
        context.register(WebConfig.class);
        
        // 注册DispatcherServlet
        ServletRegistration.Dynamic dispatcher = servletContext.addServlet("dispatcher", new DispatcherServlet(context));
        dispatcher.setLoadOnStartup(1);
        dispatcher.addMapping("/"); // 核心映射，处理所有请求
    }
}

方式2：web.xml

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">
    <servlet>
        <servlet-name>dispatcher</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>com.yourpackage.WebConfig</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-app>

第三步：排查项目结构与部署问题 #

1. Thymeleaf模板位置：必须将hello.html放在src/main/resources/templates/下，不能放在webapp目录（Thymeleaf不直接读取webapp下的文件）。
2. Tomcat部署配置：在IntelliJ中，确保项目部署的Application context为/（即访问路径是http://localhost:8080/，而非带项目名的路径）。
3. 日志排查：查看Tomcat的localhost.log和catalina.log，确认：
   • Spring容器是否正常启动，是否加载到了你的HelloController
   • DispatcherServlet是否初始化成功
   • 有没有类加载异常或配置错误的日志

关键误区说明 #

• 直接访问hello.html报404是正常的：Thymeleaf模板是需要Spring渲染的视图，不能像静态资源或JSP那样直接访问，必须通过Controller的请求映射返回视图名来触发渲染。
• JSP能正常访问是因为Tomcat本身内置了JSP解析器，不需要Spring处理，和Thymeleaf的机制完全不同。

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