Spring MVC 无法正确渲染 JSP 页面的常见原因与解决方案_技术教程

本文详解 spring mvc 项目中 jsp 视图无法显示（出现 wh

itelabel error page）的核心原因，重点聚焦于组件扫描范围配置不当、视图解析器路径错误及包结构不匹配等典型问题，并提供可立即验证的修复方案。

在 Spring MVC 项目中，控制器方法返回逻辑视图名（如 "home"），但浏览器却显示 Whitelabel Error Page，而非预期的 home.jsp，这通常并非 JSP 文件本身缺失或路径错误所致，而是 Spring 容器未能正确加载控制器或视图解析器配置失效。结合你提供的项目结构（含 DispatcherConfig、ViewResolver 和 Controller），最隐蔽却高频的问题在于：@ComponentScan 的扫描范围未覆盖控制器所在包。

✅ 正确的包结构与组件扫描配置

假设你的控制器类位于 com.example.demo.controller.HomeController，而配置类（如 WebConfig 或 DispatcherConfig）位于 com.example.config，那么必须确保 @ComponentScan 显式指定共同父包：

@Configuration
@EnableWebMvc
@ComponentScan("com.example") // ← 关键！必须扫描 com.example 及其所有子包
public class WebConfig implements WebMvcConfigurer {
    // ...
}

❌ 错误示例（常见陷阱）：

@ComponentScan("com.example.config") → 仅扫描 config 包，忽略 controller；
@ComponentScan 缺失或为空 → 默认仅扫描当前配置类所在包，无法发现控制器。

✅ ViewResolver 路径需严格匹配实际目录结构

确认 InternalResourceViewResolver 的 prefix 和 suffix 与 src/main/webapp/WEB-INF/jsp/ 下的真实路径一致：

@Bean
public ViewResolver viewResolver() {
    InternalResourceViewResolver resolver = new InternalResourceViewResolver();
    resolver.setPrefix("/WEB-INF/jsp/"); // 注意：以 '/' 开头，且与 webapp 下路径完全对应
    resolver.setSuffix(".jsp");
    resolver.setViewClass(JstlView.class); // 推荐添加，支持 JSTL 标签
    return resolver;
}

同时检查 JSP 文件实际位置：
✅ 正确路径：src/main/webapp/WEB-INF/jsp/home.jsp
❌ 错误路径：src/main/resources/templates/home.jsp（这是 Thymeleaf 路径）、src/main/webapp/jsp/home.jsp（缺少 WEB-INF/ 安全目录）

✅ 验证控制器是否被 Spring 扫描到

在控制器类上添加日志或断点，并确保其上有 @Controller 注解（非 @RestController）：

package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {

    @GetMapping("/home")
    public String showHome() {
        System.out.println("HomeController is loaded!"); // 启动时观察控制台输出
        return "home"; // 对应 /WEB-INF/jsp/home.jsp
    }
}

若该 println 从未打印，说明控制器未被扫描——此时请立即检查 @ComponentScan("com.example") 是否生效。

⚠️ 注意事项与补充建议

Tomcat 版本兼容性：Spring 6+ 官方已移除对 JSP 的原生支持（因 Servlet 6.0+ 不再要求容器实现 JSP）。若使用 Spring 6，强烈建议迁移到 Thymeleaf 或 FreeMarker；若坚持用 JSP，请降级至 Spring 5.3.x + Tomcat 9（或 10.0.x 以下）。
web.xml 非必需：基于 Java Config 的项目无需 web.xml，但需确保 SpringServletContainerInitializer 被正确触发（Maven 依赖中 spring-web 必须存在）。
Maven 依赖检查：确认 pom.xml 中包含 javax.servlet:jstl（JSP 标签库）和 org.apache.tomcat.embed:tomcat-embed-jasper（内嵌 Tomcat 运行 JSP 所需）：


    org.apache.tomcat.embed
    tomcat-embed-jasper
    provided


    javax.servlet
    jstl

✅ 总结：90% 的 “Spring MVC 不显示 JSP” 问题源于 @ComponentScan 范围过窄或 ViewResolver 路径错配。统一采用 com.example 作为根包名，并在配置类中声明 @ComponentScan("com.example")，配合正确的 /WEB-INF/jsp/ 路径，即可快速解决 Whitelabel 错误。