本文详解 spring mvc 项目中 jsp 视图无法正常渲染的典型问题，重点分析组件扫描范围配置不当导致控制器未被识别、视图解析器失效等核心原因，并提供可立即验证的配置修复方案。
在 Spring MVC 项目中，当访问映射 URL（如 /home）时返回 Whitelabel Error Page（404 或 500），而非预期的 home.jsp，通常并非 JSP 本身语法错误，而是Spring 容器未能正确加载控制器或视图解析链断裂。结合你提供的项目结构与配置片段，最常见且易被忽略的根本原因是：@ComponentScan 扫描路径未覆盖 Controller 所在包。
✅ 正确的包结构与组件扫描配置
假设你的项目采用标准 Maven 结构，且 Controller 类位于 com.example.demo.controller.HomeController，那么：
-
❌ 错误配置（仅扫描 com.example.config）：
@Configuration @EnableWebMvc @ComponentScan("com.example.config") // ← 仅扫描配置类，Controller 不在此路径下！ public class WebConfig implements WebMvcConfigurer { ... } -
✅ 正确配置（扫描父级基础包）：
@Configuration @EnableWebMvc @ComponentScan("com.example") // ← 扫描 com.example 及其所有子包（含 controller、service、config 等） public class WebConfig implements WebMvcConfigurer { ... }
? 为什么必须是 "com.example"？ 因为 @ComponentScan 的值是包前缀匹配，不是通配符。若 Controller 在 com.example.demo.controller，而扫描路径只设为 com.example.config，Spring 将完全忽略该 Controller——它根本不会被注册进 IoC 容器，自然无法响应请求，DispatcherServlet 查找不到对应 handler，最终抛出 404 并显示 Whitelabel 页面。
✅ 补充关键配置检查项（缺一不可）
确保以下配置完整、路径准确：
-
ViewResolver 必须正确定义（JSP 专用）：
@Bean public ViewResolver viewResolver() { InternalResourceViewResolver resolver = new InternalResourceViewResolver(); resolver.setPrefix("/WEB-INF/views/"); // 注意结尾斜杠 resolver.setSuffix(".jsp"); resolver.setViewClass(JstlView.class); // 启用 JSTL 支持（推荐） return resolver; } JSP 文件存放位置必须符合约定：
src/main/webapp/WEB-INF/views/home.jsp —— 路径必须与 viewResolver.setPrefix() 严格一致，且 不能放在 src/main/resources 或 src/main/java 下（这些路径不参与 Web 资源发布）。-
Controller 方法需使用 @Controller（非 @RestController）：
@Controller public class HomeController { @GetMapping("/home") public String showHome() { return "home"; // → 解析为 /WEB-INF/views/home.jsp } } -
Maven 依赖需包含 JSP 运行时支持（尤其 Spring Boot 3+ 或 Tomcat 10+）：
若使用较新 Tomcat（如 10.x），注意 javax.* 已迁移至 jakarta.*，需确认 pom.xml 中引入的是兼容版本：<!-- 对于 Tomcat 9 / Spring 5.x --> <dependency> <groupId>javax.servlet</groupId> <artifactId>jstl</artifactId> <version>1.2</version> </dependency> <!-- 对于 Tomcat 10+ / Spring 6+ --> <dependency> <groupId>jakarta.servlet.jsp.jstl</groupId> <artifactId>jakarta.servlet.jsp.jstl-api</artifactId> <version>2.0.0</version> </dependency>
⚠️ 注意事项与调试建议
- 禁用 @RestController：它会强制返回 JSON/文本，忽略 ViewResolver，永远无法跳转 JSP。
- 检查 Tomcat 日志：启动时搜索 Mapped 关键字，确认类似 Mapped "{[/home]}" 是否出现——若无，则 Controller 未被扫描。
- 验证 DispatcherServlet 映射：确保 WebApplicationInitializer 或 ServletWebServerFactory 正确注册了 DispatcherServlet，且 urlPatterns 包含 /（非 /*.html 等限制性模式）。
- 避免混合配置：勿同时使用 XML 配置（dispatcher-servlet.xml）和 Java Config，易引发冲突；统一采用一种方式。
通过将 @ComponentScan("com.example") 设为项目根包，并配合正确的视图解析路径与依赖，90% 以上的“Spring MVC 不显示 JSP”问题即可解决。记住：Spring MVC 的请求流转始于容器发现 Controller，止于 ViewResolver 定位资源——二者缺一不可。
