Thymeleaf无法作用于HTML文件，请求技术排查协助

1. 确认Spring Boot与Thymeleaf依赖版本兼容 #

Spring Boot不同版本对Thymeleaf有版本要求：

• Spring Boot 3.x 需搭配 Thymeleaf 3.1+
• Spring Boot 2.x 需搭配 Thymeleaf 3.0+

优先使用Spring Boot starter依赖自动管理版本，避免手动指定版本引发冲突：

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

2. 检查HTML文件存储路径与命名 #

Thymeleaf默认模板路径为src/main/resources/templates/，文件名必须以.html结尾。若自定义路径，需在配置文件中声明：

# application.properties 示例
spring.thymeleaf.prefix=classpath:/your-custom-templates/

3. 验证HTML页面的Thymeleaf命名空间 #

HTML根标签必须添加Thymeleaf命名空间，否则th:*属性会被视为普通HTML属性：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
</head>
<body>
    <p th:text="${demoText}">默认显示文本</p>
</body>
</html>

4. 检查控制器配置 #

• 必须使用@Controller注解（@RestController会直接返回字符串而非模板）
• 方法返回值为不带后缀的模板文件名，同时需通过Model传递数据：

@Controller
public class DemoController {
    @GetMapping("/demo")
    public String demoPage(Model model) {
        model.addAttribute("demoText", "Thymeleaf测试文本");
        // 返回templates目录下的demo.html，此处仅写demo
        return "demo";
    }
}

5. 确认Thymeleaf未被禁用 #

检查配置文件中是否误关闭了Thymeleaf自动配置：

spring.thymeleaf.enabled=true

6. 查看应用启动日志 #

启动时搜索Thymeleaf相关日志，确认模板是否被正确加载：

• 正常日志会显示TemplateResolver matched template pattern "xxx"
• 若出现"找不到模板"类错误，根据提示调整路径或文件名

7. 清除浏览器缓存 #

浏览器可能缓存旧HTML页面，按Ctrl+F5强制刷新，或使用无痕模式访问验证。

内容的提问来源于stack exchange，提问作者정지은