Thymeleaf模板渲染失败时应通过异常链定位根源：启用debug模式、递归打印getCause()、关注SpelEvaluationException等底层异常，并结合安全导航符、显式判空和IDE断点调试提升排查效率。
Thymeleaf模板渲染失败时，直接看日志常只看到 TemplateInputException 或 IllegalArgumentException 这类顶层异常，真正出问题的代码（比如某个 ${user.name.toUpperCase()} 中 user 为 null）被层层包装，堆栈被截断。Java 的异常链（cause 链）正是用来穿透这层包装、定位原始错误的利器。
启用 Thymeleaf 的详细错误模式
默认情况下，Thymeleaf 会吞掉底层异常细节以避免信息泄露。开发阶段需主动开启调试支持：
- Spring Boot 项目中，在
application.properties加：
spring.thymeleaf.cache=false
spring.thymeleaf.enabled=true
spring.thymeleaf.debug=true - 手动配置
TemplateEngine时，设置：templateEngine.setTemplateMode(TemplateMode.HTML);templateEngine.setEnableSpringELCompiler(true);（提升 EL 表达式异常可读性）
捕获并展开异常链的日志策略
在自定义 ViewResolver 或全局异常处理器中，不要只打印 e.toString()，而要递归遍历 getCause()：
- 写一个工具方法逐层打印异常链：
while (e != null) { log.error("Exception: {}, cause: {}", e.getClass().getSimpleName(), e.getMessage()); e = e.getCause(); } - 重点关注链中最早出现的
NullPointerException、PropertyNotFoundException或EvaluationException—— 它们往往就是根源，比如：org.springframework.expression.spel.SpelEvaluationException: EL1007E: Property or field 'name' cannot be found on null
在模板里加防御性表达式，让错误更早暴露
靠异常链定位是补救，提前预防更能减少排查成本：
立即学习“Java免费学习笔记（深入）”；
- 用安全导航操作符：
${user?.name?.toUpperCase()}，避免 NPE，同时让失败点更明确 - 配合
th:if做显式判空：<span th:if="${user != null}" th:text="${user.name}"></span> - 在 Controller 层校验模型数据完整性，抛出带业务含义的异常（如
IllegalStateException("user must not be null")），这类异常不会被 Thymeleaf 包装，直接进入异常链顶端
结合调试器快速跳转到真实出错行
IntelliJ IDEA / Eclipse 支持在 Thymeleaf 模板中打断点（需开启 Thymeleaf 调试支持）：
- 确保项目使用 Thymeleaf 3.0+ 和 Spring Boot 2.1+，IDE 插件能识别
th:*属性 - 在模板中某行打上断点（如
th:text="${order.items[0].price}"），运行 Debug 模式，异常发生时会停在模板对应逻辑的 Java 扩展类（如StandardExpressionEvaluator）中，此时查看当前栈帧的局部变量和cause字段，一目了然
