Spring Boot 启动成功但访问显示 Whitelabel Error Page 的常见原因有哪些？

Question

**Spring Boot 启动成功但访问显示 Whitelabel Error Page 的常见原因有哪些？** 在使用 Spring Boot 开发 Web 应用时，常遇到应用启动成功但访问页面时出现“Whitelabel Error Page”错误。常见原因包括： 1. **控制器未正确注册**：Controller 类未添加 `@Controller` 或 `@RestController` 注解，或请求路径未使用 `@RequestMapping` 等注解定义。 2. **组件扫描路径问题**：Spring Boot 主类上的 `@SpringBootApplication` 注解未扫描到 Controller 所在包。 3. **端口或路径配置错误**：服务器端口配置错误（如 `server.port` 设置不当），或访问路径与实际映射不符。 4. **Thymeleaf 或视图配置缺失**：未正确配置视图解析器或模板引擎，导致无法找到对应页面。 5. **请求路径不存在或拼写错误**：访问路径与控制器定义的路径不匹配。 排查时可查看日志中的映射注册信息或使用 `/actuator/mappings` 端点辅助诊断。

Answer 1

一、Whitelabel Error Page 简介

在 Spring Boot 应用中，当访问一个不存在的路径或控制器未正确映射时，默认会显示“Whitelabel Error Page”，这是 Spring Boot 提供的默认错误页面。

该页面通常包含以下信息：

• HTTP 状态码（如 404）
• 出错的请求路径
• 时间戳

虽然应用启动成功，但页面无法正常展示内容，说明请求未被正确路由到控制器方法。

二、常见原因分析与排查思路

以下是导致 Whitelabel Error Page 的主要因素，按照从浅入深的顺序进行分类讲解：

1. 控制器未正确注册

Spring MVC 中，控制器类必须使用 @Controller 或 @RestController 注解。如果遗漏这些注解，Spring 容器将不会将其识别为控制器。

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

若未添加 @RestController，则即使路径正确，也无法匹配请求。

2. 组件扫描路径配置问题

Spring Boot 默认只扫描主类所在包及其子包下的组件。若控制器位于其他包下且未通过 @ComponentScan 手动指定，则不会被加载。

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

建议保持包结构合理，避免此类问题。

3. 请求路径拼写错误或未定义

检查浏览器地址栏输入的 URL 是否与控制器中的 @RequestMapping 或 @GetMapping/@PostMapping 路径一致。

控制器定义路径	访问路径	是否匹配
/api/user/list	/api/user/list	是
/api/user/list	/user/list	否
/api/user/list	/api/user/list/	是（自动去除末尾斜杠）

4. 端口或上下文路径配置错误

在 application.properties 或 application.yml 中设置服务器端口和上下文路径：

server.port=8081
server.servlet.context-path=/myapp

此时应访问：http://localhost:8081/myapp/api/hello

5. Thymeleaf 或视图解析器配置缺失

若使用 Thymeleaf 模板引擎渲染 HTML 页面，需确保已添加相关依赖并配置视图解析器。

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

同时，模板文件应放置在 src/main/resources/templates 目录下，并返回对应的逻辑视图名。

6. Actuator 映射端点辅助诊断

启用 actuator 后，可通过访问 /actuator/mappings 查看所有已注册的请求映射关系。

GET /actuator/mappings

输出结果示例如下（简化版）：

{
  "mappings": {
    "dispatcherServlets": {
      "default": [
        {
          "handler": "com.example.controller.HelloController#sayHello",
          "predicate": "/hello"
        }
      ]
    }
  }
}

通过此接口可快速确认路径是否注册成功。

7. 日志输出验证映射情况

启动日志中通常会打印出所有注册的请求映射：

2025-04-05 10:00:00.000  INFO 12345 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped GET /hello onto public java.lang.String com.example.controller.HelloController.sayHello()

若未看到预期路径，说明控制器未被正确加载。

8. 内嵌服务器未正确初始化

极少数情况下，Spring Boot 使用的 Tomcat、Jetty 等内嵌服务器可能未正确初始化 Web 容器，导致请求未被处理。

可在启动日志中查找类似如下信息：

Tomcat started on port(s): 8080 (http) with context path ''

若无此信息，可能是启动过程中发生异常。

三、流程图：Whitelabel Error Page 排查流程

以下是一个简单的排查流程图，帮助开发者系统性地定位问题：

graph TD
    A[应用启动成功] --> B{访问路径是否存在？}
    B -- 是 --> C{控制器是否注册？}
    C -- 是 --> D{组件扫描路径是否正确？}
    D -- 是 --> E{Thymeleaf/视图是否配置？}
    E -- 是 --> F[访问成功]
    E -- 否 --> G[Whitelabel Error Page]
    D -- 否 --> G
    C -- 否 --> G
    B -- 否 --> G