Thymeleaf 实战避坑指南：5 个让你加班的坑及修复方案
Thymeleaf 官方文档写得像天书，翻了三遍还是报错？别慌，这篇避坑指南专治各种“文档看哭”。
作为用了五年 Thymeleaf 的老兵，我见过太多新人被简单的模板语法搞崩溃。很多人以为 Thymeleaf 就是“在 HTML 里加点标签”，结果一跑起来，页面全乱了，数据出不来，或者干脆白屏。
今天不扯虚的，直接上干货。我们跳过那些晦涩的原理推导，直接看现象、原因、对比、修复。全是踩坑后换来的血泪经验，保证你看完就能上手，不再对着报错信息发呆。
坑一：浏览器直接打开模板，标签全裸露
现象：
你写完一个 index.html，双击用浏览器打开，发现页面上全是 th:text=... 这种奇怪的标签，原本应该显示“你好”的地方变成了代码字符串。
根本原因：
这是新手最经典的误区。Thymeleaf 是服务器端模板引擎。它需要在 Java 后端处理时，解析 th: 开头的属性，替换成标准的 HTML 属性。
如果你直接用浏览器打开本地文件（file:///...），浏览器根本不认识 th: 属性，它只认标准的 id、class、src 等。所以，它把这些当作普通属性显示出来了。
错误写法：
直接双击 HTML 文件，或者在本地静态服务器（如 Live Server）预览。
正确写法：
必须通过 Spring Boot 启动后的 URL 访问，例如 http://localhost:8080/index。
代码对比：
!-- 错误：本地直接打开时，浏览器无法解析 th:text --
p th:text=${username}默认文本/p!-- 正确：在 Spring Boot 控制器中返回该视图，浏览器收到的将是： --
p张三/p复现与修复：确保你的 Spring Boot 应用已启动。
控制器返回视图名：return index;。
浏览器访问 http://localhost:8080/index。
如果还是看到 th: 标签，检查 pom.xml 是否引入了 spring-boot-starter-thymeleaf。规避建议：
永远不要试图用浏览器直接调试 Thymeleaf 模板的逻辑。如果你需要在本地看效果，请启动后端。如果只想看样式，可以先去掉 th: 属性，写死一些测试数据，但切记不要提交这种“假数据”代码到仓库。
坑二：th:each 遍历列表，索引和状态丢失
现象：
你要遍历一个列表，显示“第 1 项”、“第 2 项”，并且想在第一项前加个“首”字。结果发现，th:each 里的变量名写错了，或者根本拿不到索引。
根本原因：
Thymeleaf 的 th:each 语法在版本迭代中变化很大。老版本用的是 item, status，新版本推荐用 item : list。很多教程还在教旧的写法，导致新手复制粘贴后报错或变量未定义。
另外，status 对象（或 th:each 的 status 属性）是获取索引、当前项状态的关键，但很多人不知道它叫什么名字。
错误写法：
混用旧语法，或者变量名冲突。
!-- 错误：旧版语法，且变量名容易混淆 --
li th:each=item : ${userList} th:text=${item.name} + ' - 索引: ' + ${item}!-- 这里 ${item} 指的是当前项，而不是索引！ --
/li正确写法：
使用标准的 th:each 语法，明确指定迭代变量和状态变量。
!-- 正确：status 变量用于获取索引、计数等 --
ulli th:each=user, stat : ${userList}span th:text=${stat.index + 1}1/span. span th:text=${user.name}默认名/span!-- 判断是否是第一项 --em th:if=${stat.first}【首】/em!-- 判断是否是最后一项 --em th:if=${stat.last}【尾】/em/li
/ul复现与修复：控制器传递列表：model.addAttribute(userList, userList);
在模板中，th:each 的格式是 itemVar, statusVar : collection。
使用 stat.index 获取从 0 开始的索引，stat.count 获取从 1 开始的计数。
使用 stat.first 和 stat.last 布尔值判断边界。规避建议：
在 GitHub 开源仓库（如 Spring 官方示例）中，th:each 的标准写法非常清晰。建议收藏一个常用的 Thymeleaf 语法速查表，不要每次去翻冗长的官方文档。记住：索引从 0 开始，这是大多数前端和后端开发者的思维定式，Thymeleaf 也不例外。
坑三：th:src 拼接静态资源路径，图片加载失败
现象：
你在模板里写 th:src=@{img/logo.png}，页面刷新后，图片裂了。控制台报错 404。
或者你写 th:src=@{${cssPath}}，结果路径变成了 /css/theme/main.css，但实际资源在 /static/css/theme/main.css。
根本原因：
Thymeleaf 的 @{...} 语法是URL 处理语法。它会自动处理上下文路径（Context Path）。
如果你的应用部署在 http://localhost:8080/myapp，那么 @{/img/logo.png} 会被解析为 http://localhost:8080/myapp/img/logo.png。
但静态资源默认在 src/main/resources/static 下，Spring Boot 会自动映射到 / 根路径下。
坑在于：很多项目设置了 server.servlet.context-path=/myapp，但静态资源路径配置没跟上，或者开发者手动拼接了 /static 前缀，导致路径变成 /myapp/static/img/logo.png，而实际资源在 /myapp/img/logo.png。
错误写法：
!-- 错误：手动加了 /static，导致路径重复或错误 --
img th:src=@{/static/img/logo.png} alt=Logo!-- 错误：如果 Context Path 存在，@{img/logo.png} 可能找不到，因为相对路径处理复杂 --
img th:src=@{img/logo.png} alt=Logo正确写法：
!-- 正确：使用根路径 /，让 Thymeleaf 自动处理 Context Path --
img th:src=@{/img/logo.png} alt=Logo!-- 如果资源在特定的子目录，且想确保绝对路径，可以这样： --
link th:href=@{/css/theme/main.css} rel=stylesheet复现与修复：检查 application.properties 中的 server.servlet.context-path。
如果设置了 Context Path，确保所有 @{...} 都以 / 开头。
不要手动拼接 /static。Spring Boot 的静态资源处理是透明的。
如果使用了 CDN 或外部资源，不要用 @{...}，直接用完整 URL。规避建议：
在复杂项目中，建议封装一个工具类或 Thymeleaf 的 AbstractModelProcessor，统一处理静态资源路径。但最简单的方法是：养成习惯，所有内部资源路径都以 / 开头，并使用 @{...} 语法。 这样无论 Context Path 怎么变，代码都不用改。
坑四：th:fragment 复用失败，JS 和 CSS 没加载
现象：
你写了 header.html 和 footer.html，通过 th:replace=~{fragments :: header} 引入。
结果，HTML 结构出来了，但里面的 script 和 link 标签没生效，JS 报错，样式丢失。
根本原因：
Thymeleaf 的片段替换是DOM 节点级别的。
如果你在 header.html 里写了 script src=...，当它被替换到主页面时，这些脚本会被执行。
但坑在于：执行时机。
如果主页面中也有 script，而片段的 script 在 DOM 中位置不对，或者浏览器在解析时，JS 文件还没加载完，就会导致“函数未定义”错误。
另外，很多新手把 JS 逻辑写在 HTML 标签属性里（如 onclick），而片段替换后，这些属性可能因为作用域问题失效。
错误写法：
!-- header.html --
headerscript src=js/header.js/script !-- 坑：如果 header.js 依赖全局变量，而全局变量在主页面后面定义，就会报错 --
/header正确写法：
!-- header.html --
header th:fragment=headernav.../nav!-- 不要在这里放复杂的 JS 逻辑，只放结构 --
/header!-- index.html --
bodyheader th:replace=~{fragments :: header}/headermain.../main!-- 所有 JS 放在页面底部，确保 DOM 加载完成 --script src=js/app.js/script
/body复现与修复：将片段的 script 和 link 移到主模板的 head 或 body 底部。
片段只包含 HTML 结构。
如果需要复用 JS 逻辑，使用模块化加载（如 ES6 Modules 或 Webpack），而不是直接在片段里写 script。
检查浏览器控制台，看是否有 ReferenceError，通常是执行顺序问题。规避建议：
片段只负责结构，不负责逻辑。 这是前端工程化的基本准则。把 JS 和 CSS 的引入统一放在主模板的 head 中，通过 th:fragment 引入时，只引入 HTML 节点。如果需要动态加载 JS，使用 th:with 或控制器判断，在主模板中条件性引入。
坑五：数据为 null 时，页面直接报错或显示 null
现象：
后台传了一个用户对象，但 user.getNickName() 返回 null。
页面上显示了字符串 null，而不是空白或默认值。
更严重的是，如果 user 本身是 null，页面直接抛出 TemplateProcessingException，白屏。
根本原因：
Thymeleaf 默认不会自动处理 null 值。th:text=${user.nickName} 如果 nickName 是 null，它会输出 null 字符串。
如果 user 是 null，访问 user.nickName 会抛出空指针异常。
错误写法：
!-- 错误：直接访问，没有判空 --
p th:text=${user.nickName}默认昵称/p
p th:text=${user.email}默认邮箱/p正确写法：
使用 Thymeleaf 的安全导航操作符 ?. 和默认值语法。
!-- 正确：使用 ?. 安全导航，如果 user 为 null，则整个表达式为 null，显示默认文本 --
p th:text=${user?.nickName} ?: '未设置昵称'未设置昵称/p!-- 或者使用 if 判断 --
p th:if=${user != null and user.nickName != null} th:text=${user.nickName}未设置/p
p th:unless=${user != null and user.nickName != null}未设置昵称/p复现与修复：使用 ?. 操作符：user?.nickName。如果 user 是 null，结果为 null，不会报错。
使用 ?: 操作符提供默认值：${user?.nickName ?: '默认'}。
如果对象嵌套较深，如 user.address.city，使用 user?.address?.city。
在控制器中，尽量保证传入模型的对象不为 null，或者传入空对象（Empty Object）而不是 null。规避建议：
永远不要相信后台传过来的数据是完整的。 前端模板必须做防御性编程。
推荐在 Thymeleaf 中统一使用 ?. 和 ?:。
另外，考虑使用 Lombok 的 @Data 注解生成 getter，确保字段名拼写正确。
如果项目复杂，可以封装一个 Thymeleaf 的 SpringELVariableExpressionEvaluator，统一处理 null 值转换。
总结与互动
Thymeleaf 的强大在于它的原生 HTML 特性，但也正是这一点，让很多前端开发者容易踩坑。
记住这五个坑：必须通过服务器访问，不能本地双击。
th:each 语法要分清版本，用 stat 获取索引。
静态资源路径用 @{/...}，别手动拼 /static。
片段只含结构，JS/CSS 放主模板。
防御性编程，用 ?. 和 ?: 处理 null。这些坑，每一个都可能导致项目延期。避坑指南的核心不是让你记住语法，而是让你建立正确的调试思维：先确认执行环境，再检查语法版本，最后处理边界情况。
你在项目里踩过 Thymeleaf 的哪个坑？是 th:each 的索引搞混了，还是静态资源路径怎么都加载不出来？评论区聊聊，互相抄作业，少走弯路。
