Spring Boot 3整合Thymeleaf遇TemplateOutputException问题求助

问题概述 #

开发LDAP认证+MySQL授权的POC项目，应用启动、认证授权流程正常，但Thymeleaf视图渲染时抛出异常：

org.thymeleaf.exceptions.TemplateOutputException: An error happened during template rendering

使用Spring Boot 3.0.4版本，相关源码及异常日志已上传至GitHub仓库。

排查方向 #

1. 定位根本异常 #

TemplateOutputException是包装类异常，直接查看日志中的Caused by片段，这是触发渲染失败的核心原因：

• 常见底层问题：空指针异常（模板引用未初始化的变量）、EL表达式语法错误、模板文件路径不匹配、Spring Security权限标签使用错误

2. 校验Thymeleaf模板语法 #

• 检查所有EL表达式（${}、`*{}）的变量名是否与控制器传递的Model属性完全匹配，避免拼写错误
• 确认th:each、th:if等标签的逻辑：比如循环集合是否为空时未做非空判断，导致遍历空对象
• 验证模板文件存放路径：必须在src/main/resources/templates下，文件名与控制器返回的视图名一致（注意大小写）

3. 检查Spring Security与Thymeleaf集成 #

• 确认已引入适配Spring Boot 3的依赖：spring-boot-starter-thymeleaf-extras-springsecurity6
• 模板文件头部需声明Spring Security命名空间：xmlns:sec="http://www.thymeleaf.org/extras/spring-security"
• 测试模板中${principal}或自定义UserDetails对象的属性访问是否正常，避免因用户信息未正确传递导致的异常

4. 核对Model数据传递 #

• 检查控制器方法中是否将模板所需的所有变量添加到Model中，无遗漏
• 若使用自定义UserDetails，确保其属性都有对应的getter方法，模板中访问的属性名与getter命名规范一致

5. 版本兼容性验证 #

Spring Boot 3.0.4对应Thymeleaf 3.1.x版本：

• 排查依赖树，确认Thymeleaf及相关扩展的版本与Spring Boot版本兼容，无冲突
• 避免引入独立的Thymeleaf依赖，优先使用Spring Boot starter管理版本

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