Spring Boot整合Thymeleaf访问根路径出现白标错误页问题排查

我搭建了一个整合Thymeleaf与PostgreSQL的Spring Boot项目，访问localhost:8090根路径时无法展示test.html页面，返回Whitelabel Error Page（404未找到错误）。

项目结构说明 #

• src/main/resources/templates/test.html：Thymeleaf模板文件
• src/main/java/com/example/demo/controller/HomeController.java：处理根路径请求的控制器
• 核心配置文件位于src/main/resources目录

HomeController代码 #

package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {

    @GetMapping("/")
    public String showCodeEditor() {
        return "test"; // 对应templates目录下的test.html（无需后缀）
    }
}

POM配置 #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.2</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>19</source>
                    <target>19</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

test.html内容 #

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Test Page</title>
</head>
<body>
<h1>This is a test page</h1>
<p>If you see this, the template setup is working.</p>
</body>
</html>

application.properties配置 #

spring.datasource.url=jdbc:postgresql://localhost:5433/coder
spring.datasource.username=postgres
spring.datasource.password=password123
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.properties.hibernate.format_sql=true
server.port = 8090
server.error.include-message=always
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html
spring.thymeleaf.cache=false
spring.thymeleaf.encoding=UTF-8
spring.thymeleaf.mode=HTML5

错误现象 #

访问localhost:8090时显示：

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

Fri Aug 25 18:08:28 BST 2023
There was an unexpected error (type=Not Found, status=404).
No message available

排查与解决建议 #

1. 修复Java版本冲突 #

POM中java.version配置为17，但maven-compiler-plugin指定source和target为19，版本不匹配会导致控制器类未被正确编译加载。修改插件配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>17</source>
        <target>17</target>
    </configuration>
</plugin>

2. 确认主类包扫描范围 #

确保Spring Boot启动类（如DemoApplication.java）位于com.example.demo包下，这样才能自动扫描到com.example.demo.controller包中的控制器。若启动类在子包，需添加@ComponentScan(basePackages = "com.example.demo")注解。

3. 清理并重新编译项目 #

删除target目录，执行mvn clean install后重启项目，确保test.html被正确打包到classpath:/templates/目录。

4. 验证数据库连接 #

查看启动日志，确认PostgreSQL连接是否正常。若数据库连接失败，会导致Spring Boot启动不完全，控制器未注册。可临时注释数据库配置，先验证Thymeleaf页面是否能访问，再排查数据库问题。

5. 添加日志排查控制器注册 #

在application.properties中添加日志配置：

logging.level.org.springframework.web=DEBUG

启动后查看日志，若出现Mapped "{[/]}" onto public java.lang.String com.example.demo.controller.HomeController.showCodeEditor()，说明控制器映射已生效。

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