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 变量用于获取索引、计数等 -->
<ul><li 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 -->
<header><script src="js/header.js"></script> <!-- 坑：如果 header.js 依赖全局变量，而全局变量在主页面后面定义，就会报错 -->
</header>
正确写法：
<!-- header.html -->
<header th:fragment="header"><nav>...</nav><!-- 不要在这里放复杂的 JS 逻辑，只放结构 -->
</header><!-- index.html -->
<body><header th:replace="~{fragments :: header}"></header><main>...</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 的索引搞混了，还是静态资源路径怎么都加载不出来？评论区聊聊，互相抄作业，少走弯路。
