Spring Boot+Thymeleaf布局问题：无法替换content片段

核心语法修正方案 #

先确认你是否用对了Thymeleaf的片段替换逻辑，以下是两种可行的实现方式：

方式1：原生Thymeleaf片段替换 #

布局文件（layout.html）调整

确保可替换区域明确标记为片段，公共部分保留：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <!-- 公共样式 -->
    <link rel="stylesheet" th:href="@{/css/common.css}">
</head>
<body>
    <!-- 公共导航栏 -->
    <nav th:fragment="navbar">
        <div>导航栏内容</div>
    </nav>

    <!-- 可替换内容占位 -->
    <div th:fragment="content">
        请替换此默认内容
    </div>

    <!-- 公共页脚 -->
    <footer th:fragment="footer">
        <div>页脚内容</div>
    </footer>

    <!-- 公共JS -->
    <script th:src="@{/js/common.js}"></script>
</body>
</html>

页面文件（index.html）写法

通过th:replace引用布局片段并替换content：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>首页</title>
</head>
<body>
    <!-- 引入公共导航 -->
    <div th:replace="~{layout :: navbar}"></div>

    <!-- 替换布局的content片段 -->
    <div th:replace="~{layout :: content}">
        <!-- 这里是你的首页实际内容 -->
        <h1>欢迎访问首页</h1>
        <p>这是首页专属内容</p>
    </div>

    <!-- 引入公共页脚 -->
    <div th:replace="~{layout :: footer}"></div>
</body>
</html>

方式2：使用Thymeleaf布局方言（更简洁的继承式布局） #

这是官方推荐的布局方式，适合复杂场景：

1. 添加依赖（Spring Boot）
   Maven：

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

   Gradle：

   implementation 'nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect'
   

2. 布局文件（layout.html）调整
   添加布局命名空间，用layout:fragment标记可替换区域：

   <!DOCTYPE html>
   <html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
   <head>
       <title layout:title-pattern="$CONTENT_TITLE - 我的应用">我的应用</title>
       <link rel="stylesheet" th:href="@{/css/common.css}">
   </head>
   <body>
       <nav>
           <div>导航栏内容</div>
       </nav>
   
       <!-- 可替换内容区域 -->
       <div layout:fragment="content">
           默认内容
       </div>
   
       <footer>
           <div>页脚内容</div>
       </footer>
   
       <script th:src="@{/js/common.js}"></script>
   </body>
   </html>
   

3. 页面文件（index.html）继承布局
   用layout:decorate指定布局文件，并用layout:fragment覆盖content：

   <!DOCTYPE html>
   <html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
         layout:decorate="~{layout}">
   <head>
       <title>首页</title>
   </head>
   <body>
       <div layout:fragment="content">
           <h1>欢迎访问首页</h1>
           <p>这是首页专属内容</p>
       </div>
   </body>
   </html>
   

常见排查点 #

• 命名空间缺失：确保所有模板文件都声明了xmlns:th="http://www.thymeleaf.org"，用布局方言的话还要加xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
• 片段路径错误：如果布局文件放在templates/layouts/目录下，引用时要写成~{layouts/layout :: content}，路径要和实际文件结构匹配
• 片段名称不匹配：布局中th:fragment="content"的名称和页面引用的必须完全一致（大小写敏感）
• 替换指令错误：th:replace是完全替换目标片段，th:insert是插入到目标位置，别搞混；用布局方言必须配合layout:decorate和layout:fragment
• Spring Boot配置检查：确认application.properties中spring.thymeleaf.prefix是classpath:/templates/（默认配置正确，除非你手动修改过）

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