本文详解 spring mvc 项目中 jsp 视图无法显示（出现 whitelabel 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 所需）：
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-jasper</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
</dependency>✅ 总结：90% 的 “Spring MVC 不显示 JSP” 问题源于 @ComponentScan 范围过窄或 ViewResolver 路径错配。统一采用 com.example 作为根包名，并在配置类中声明 @ComponentScan("com.example")，配合正确的 /WEB-INF/jsp/ 路径，即可快速解决 Whitelabel 错误。
