Thymeleaf 的 th:each 不能直接作用于 标签进行循环渲染，否则会导致模板解析异常或数据不显示；正确做法是使用 作为逻辑容器包裹循环体，确保 HTML 结构合法且迭代逻辑清晰。

thymeleaf 的 `th:each` 不能直接作用于 `

` 标签进行循环渲染，否则会导致模板解析异常或数据不显示；正确做法是使用 `` 作为逻辑容器包裹循环体，确保 html 结构合法且迭代逻辑清晰。

在 Thymeleaf 模板中，th:each 是最常用的迭代指令之一，用于遍历集合（如 List）并动态生成重复结构。但一个常见误区是：将 th:each 直接添加到语义化标签（如 ）上，却忽略了该标签在 DOM 层级中的上下文约束。

例如，以下写法看似合理，实则存在隐患：

<tr th:each="data : ${stats}">
    <td th:text="${data.country}"></td>
    <td th:text="${data.state}"></td>
    <td th:text="${data.latestTotalCases}">0</td>
</tr>

⚠️ 问题根源在于：当 th:each 应用于

时，Thymeleaf 会尝试对每个元素复制整个 标签及其所有子节点。若后端传入的 stats 为空列表或为 null，Thymeleaf 默认不会报错，而是静默跳过渲染——导致页面“空白”；更严重的是，某些版本的 Thymeleaf（尤其配合严格 HTML 解析器时）可能因模板结构不规范（如循环体嵌套逻辑混乱）而拒绝渲染，或引发不可预期的 DOM 错位。

✅ 正确解法：使用 作为无语义的逻辑分组容器，将 th:each 移至其上，再在内部生成标准 结构：

<th:block th:each="data : ${stats}">
    <tr>
        <td th:text="${data.country}">Country Placeholder</td>
        <td th:text="${data.state}">State Placeholder</td>
        <td th:text="${data.latestTotalCases}">0</td>
    </tr>
</th:block>

这样做的优势包括：

• ✅ 结构安全： 不生成实际 DOM 节点，仅作模板逻辑分组，避免破坏表格层级（如 → → 的合法性）；
  ✅ 空集合友好：若 ${stats} 为空或 null， 内容自然不渲染，页面不会出现冗余
  或占位内容；
  ✅ 可读性与可维护性高：迭代逻辑与展示结构分离，便于后续扩展（如添加条件判断、索引变量等）。

  ? 进阶提示：你还可以利用 th:each 提供的迭代状态变量增强控制能力，例如：

  <th:block th:each="data, iter : ${stats}">
      <tr th:classappend="${iter.odd} ? 'odd-row' : 'even-row'">
          <td th:text="${data.country}"></td>
          <td th:text="${data.state}"></td>
          <td th:text="${data.latestTotalCases}">0</td>
          <td th:text="${iter.index + 1}">#</td> <!-- 从 1 开始的序号 -->
      </tr>
  </th:block>

  ? 最后务必确认后端 Controller 已正确将数据放入 Model：

  model.addAttribute("stats", statService.getAllStats()); // 确保非 null，建议返回 Collections.emptyList() 而非 null

  总结：th:each 的本质是模板级循环指令，其宿主标签应优先选择无语义、零副作用的 ，而非承担结构职责的 HTML 元素（如

  、
  在特定上下文中也可能引发嵌套问题）。遵循这一原则，可显著提升 Thymeleaf 模板的健壮性与可调试性。