Thymeleaf-Layout-Dialect布局装饰失效问题求助

排查步骤与解决方案 #

1. 确认模板文件位置 #

Spring Boot中Thymeleaf模板默认存放路径为src/main/resources/templates/，请确保_layout.html和index2.html都放在该目录下，禁止放在static目录——static目录下的文件会被直接当作静态资源返回，不会触发Thymeleaf模板引擎解析，布局逻辑自然无法生效。

2. 检查控制器映射配置 #

必须通过Spring MVC控制器返回模板页，确保存在如下控制器代码：

@Controller
public class PageController {
    @GetMapping("/index2")
    public String showIndex2() {
        return "index2"; // 对应templates目录下的index2.html
    }
}

若直接访问/index2.html，会绕过控制器直接返回静态文件，无法触发布局装饰逻辑。

3. 优化依赖版本兼容性 #

你的Spring Boot 2.7.6搭配Thymeleaf Layout-Dialect 3.0.0本身兼容，但可以依赖Spring Boot的版本管理自动匹配兼容版本，修改build.gradle中的布局方言依赖：

// 移除手动指定的版本号
implementation 'nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect'

Spring Boot的依赖管理会自动适配最合适的版本，避免版本冲突问题。

4. 核对Thymeleaf全局配置 #

检查application.properties（或application.yml）中的Thymeleaf前缀配置，确保路径与模板文件位置匹配：

# 默认配置无需修改，若自定义路径需保证正确性
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html

5. 清理缓存并重启应用 #

若使用spring-boot-devtools，缓存可能导致模板更新不生效。可以手动清理项目target目录后重启应用，或在开发环境关闭Thymeleaf缓存：

spring.thymeleaf.cache=false

验证效果 #

完成上述操作后，访问控制器映射路径（如http://localhost:8080/index2），页面应显示布局中的<h1>My website</h1>头部，以及内容页的段落文本，证明布局装饰生效。

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