Spring Boot 3.0.2集成Thymeleaf仅加载index.html，其他页面报错求助

1. 先确认请求路径映射匹配 #

白标错误核心原因是请求找不到对应Controller处理逻辑，优先检查：

• 查看index.html中注册表单的action属性值（比如是否为/register），对比Controller中是否存在对应请求方法的映射（如@PostMapping("/register")）。
• 注意路径大小写，Spring Boot默认请求映射大小写敏感，若需忽略可在application.properties添加配置：spring.mvc.pathmatch.matching-strategy=ant_path_matcher。

2. 修正Thymeleaf版本兼容性 #

Spring Boot 3.0.2基于Jakarta EE规范，而你手动指定的Thymeleaf 3.0.2部分API仍依赖Java EE，存在兼容风险。建议移除手动版本指定，使用Spring Boot依赖管理自动匹配兼容版本：

<!-- pom.xml中修改Thymeleaf依赖，移除自定义版本 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

3. 验证包结构扫描范围 #

Spring Boot主类WebDemoApplication的@SpringBootApplication注解默认扫描自身所在包及其子包下的组件。确保Controller所在包是主类包的子包：

• 例：主类在com.example.webdemo，Controller需放在com.example.webdemo.controller或更深子包，而非com.example.controller。

4. 检查模板文件位置与视图返回 #

Thymeleaf默认模板目录为src/main/resources/templates/，确保注册相关页面（如register.html或register-success.html）在此目录下，且Controller返回的视图名称与文件名一致（无需加.html后缀）。

附：标准代码与目录参考 #

pom.xml 正确配置示例

<?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.0.2</version>
        <relativePath/>
    </parent>
    <groupId>com.example</groupId>
    <artifactId>web-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <properties>
        <java.version>19</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

HomeController 示例代码

package com.example.webdemo.controller;

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

@Controller
public class HomeController {

    @GetMapping("/")
    public String index() {
        return "index";
    }

    // 与表单action路径完全匹配
    @PostMapping("/register")
    public String handleRegister() {
        // 此处添加注册逻辑
        return "register-success";
    }
}

WebDemoApplication 主类示例

package com.example.webdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class WebDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(WebDemoApplication.class, args);
    }
}

标准项目目录结构

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── example/
│   │           └── webdemo/
│   │               ├── WebDemoApplication.java
│   │               └── controller/
│   │                   └── HomeController.java
│   └── resources/
│       ├── templates/
│       │   ├── index.html
│       │   └── register-success.html
│       └── application.properties
└── pom.xml

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