遵循Spring Boot官方包结构仍出现Whitelabel Error如何解决

我在应用开发过程中严格遵循Spring Boot官方的文件与包结构规范，但仍然出现Whitelabel Error Page报错。

[Whitelabel Error Page报错截图]

以下是我的代码实现、配置内容以及项目文件目录结构示意：

Controller

@Controller
public class UserController {
    @RequestMapping("/")
    public String index(HttpServletRequest request) {
        request.setAttribute("mode", "MODE_HOME");
        return "homepage";
    }
}

homepage.jsp

<body>
<c:choose>
<c:when test="${mode=='MODE_HOME'}">
<h1>Mambo, this is home page </h1>
</c:when>
</c:choose>
</body>

application.properties

spring.mvc.view.prefix=/WEB-INF/view/
spring.mvc.view.suffix=.jsp

pom.xml 相关依赖

<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-jasper</artifactId>
    <scope>provided</scope>
</dependency>

<dependency>
    <groupId>jstl</groupId>
    <artifactId>jstl</artifactId>
    <version>1.2</version>
</dependency>

[项目文件目录结构截图]

已排查一整天配置与实现问题，仍未解决该报错，请求指导。

按优先级排查以下问题：

1. 确认Controller扫描范围 #

Spring Boot默认仅扫描主启动类所在包及下级子包下的组件，若UserController不在扫描范围内，会导致请求映射未注册，直接触发404错误。

• 主启动类需放置在项目根包下（例如com.example.demo）
• UserController必须放在主启动类的同级或下级子包中，不能放在主启动类的上级包
• 可显式指定扫描范围避免漏扫：

@SpringBootApplication(scanBasePackages = {"com.example.demo"})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

2. 修正JSP存放路径 #

Spring Boot内嵌Tomcat不会加载src/main/resources或src/main/java路径下的WEB-INF目录，JSP必须放置在：

src/main/webapp/WEB-INF/view/homepage.jsp

完全匹配你配置的视图前缀/WEB-INF/view/，否则无法解析视图。

3. 修正tomcat-embed-jasper依赖配置 #

• 移除<scope>provided</scope>配置，否则运行时无法加载JSP解析器（provided范围的依赖不会打入运行时环境）
• 推荐使用Spring Boot官方管理的版本，避免版本冲突：

<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-jasper</artifactId>
</dependency>

注意：JSP场景不支持打可执行jar包，需修改pom.xml打包方式为war：

<packaging>war</packaging>

同时主启动类需继承SpringBootServletInitializer：

@SpringBootApplication
public class Application extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(Application.class);
    }
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

4. 替换兼容的JSTL依赖 #

当前使用的jstl:jstl:1.2为旧版依赖，存在兼容问题，替换为标准实现：

<dependency>
    <groupId>javax.servlet.jsp.jstl</groupId>
    <artifactId>jstl-api</artifactId>
    <version>1.2</version>
</dependency>
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>jstl-impl</artifactId>
    <version>1.2</version>
</dependency>

或直接使用Spring Boot官方starter：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jstl</artifactId>
</dependency>

5. 修正IDE运行配置 #

如果使用IDEA开发，需确认已将src/main/webapp标记为Web资源目录：

• 打开项目结构 → Facets → 对应Web模块
• 确认Web资源目录为src/main/webapp，未勾选「相对类路径」选项

6. 开启错误详情排查 #

若以上配置均正确，可在application.properties中添加以下配置，直接查看真实报错原因：

server.error.include-stacktrace=always
server.error.include-message=always

访问报错路径后会显示完整异常堆栈，可直接定位是视图解析失败、还是Controller未注册的问题。

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