Spring MVC 无法显示 JSP 页面的常见原因与解决方案_网络技术

本文详解 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 中引入的是兼容版本：
```
    javax.servlet
    jstl
    1.2



    jakarta.servlet.jsp.jstl
    jakarta.servlet.jsp.jstl-api
    2.0.0
```

⚠️ 注意事项与调试建议

禁用 @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 定位资源——二者缺一不可。

# java # html # js # json # app # tomcat # ai # spring mvc # 为什么

相关栏目：【网站优化151355 】【网络推广146373 】【网络技术251813 】【 AI营销90571 】