Thymeleaf布局无法渲染子内容：仅显示页眉页脚问题排查

问题描述 #

使用Thymeleaf 3搭配base.html基础布局和index.html子模板，页眉、页脚可正常显示，但子模板中的Hero等内容无法注入最终页面。浏览器F12查看源码发现<main>元素为空，子模板内容区块完全未加载。已尝试th:replace="~{base :: layout}"、匹配th:fragment="content"、清理缓存重建项目等操作，问题仍存在。

排查与解决步骤 #

1. 修正布局引用逻辑 #

Thymeleaf原生布局的核心是子模板继承基础布局并替换指定片段，而非直接替换整个布局。错误的引用方式会导致子模板内容被覆盖，正确写法如下：

base.html（基础布局）

在<main>标签定义可替换的片段占位符：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title th:text="${pageTitle}">默认标题</title>
</head>
<body>
    <header>
        <!-- 页眉固定内容 -->
    </header>
    <!-- 定义内容占位片段 -->
    <main th:fragment="content">
        <!-- 可选：默认填充内容 -->
    </main>
    <footer>
        <!-- 页脚固定内容 -->
    </footer>
</body>
</html>

index.html（子模板）

通过th:replace继承基础布局，并替换其content片段：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="base :: html">
<head>
    <title th:text="首页">首页</title>
</head>
<body>
    <!-- 替换base中的content片段 -->
    <main th:fragment="content">
        <section class="hero">
            <!-- Hero区块具体内容 -->
        </section>
        <!-- 其他子模板专属内容 -->
    </main>
</body>
</html>

2. 推荐使用Thymeleaf Layout Dialect（更简洁不易出错） #

若引入官方布局方言，可简化布局逻辑：

添加Maven依赖

<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
</dependency>

base.html（基础布局）

用layout:fragment标记占位区域：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
    <meta charset="UTF-8">
    <title layout:title-pattern="$CONTENT_TITLE - $LAYOUT_TITLE">站点总标题</title>
</head>
<body>
    <header>
        <!-- 页眉内容 -->
    </header>
    <main layout:fragment="content">
        <!-- 占位区域 -->
    </main>
    <footer>
        <!-- 页脚内容 -->
    </footer>
</body>
</html>

index.html（子模板）

用layout:decorate指定继承的布局，并填充content片段：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout" layout:decorate="~{base}">
<head>
    <title>首页</title>
</head>
<body>
    <main layout:fragment="content">
        <section class="hero">
            <!-- Hero区块内容 -->
        </section>
    </main>
</body>
</html>

3. 检查控制器返回路径 #

确保控制器返回的是子模板名称，而非基础布局：

@Controller
public class HomeController {
    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("pageTitle", "首页");
        return "index"; // 返回子模板，而非base
    }
}

4. 验证片段名称匹配 #

确认基础布局和子模板中的片段名称完全一致（大小写敏感），比如base中是th:fragment="content"，子模板中不能写成Content或main-content。

5. 强制清理编译缓存 #

若target目录下的模板已更新但页面未生效：

• 执行mvn clean install（Maven）或./gradlew clean build（Gradle）
• 重启应用服务器，确保加载最新模板文件

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