SpringBoot集成Thymeleaf引入Fragment后页面空白问题求助

1. 核对片段文件路径与命名 #

• 确认片段文件（如common-header.html）放置在Thymeleaf默认模板目录src/main/resources/templates下，子目录需在引用时明确指定
• 片段引用路径要完全匹配，比如片段存于fragments/common-header.html，主页面需写~{fragments/common-header::common-header}，避免写错片段名或文件路径

2. 验证片段语法合法性 #

• 片段定义必须使用正确的th:fragment标签，示例：

  <!-- common-header-imports 片段 -->
  <th:block th:fragment="common-header-imports">
    <link rel="stylesheet" href="/css/style.css">
    <script src="/js/main.js"></script>
  </th:block>
  
  <!-- common-header 片段 -->
  <header th:fragment="common-header">
    <nav>
      <a href="/">首页</a>
      <a href="/about">关于</a>
    </nav>
  </header>
  

• 片段内容不能存在未闭合标签、错误Thymeleaf表达式等语法问题，这类错误会直接导致模板解析失败

3. 检查主页面引入逻辑 #

• 主页面必须声明Thymeleaf命名空间xmlns:th="http://www.thymeleaf.org"，否则所有Thymeleaf标签会被浏览器忽略
• th:replace标签使用需规范，示例：

  <!DOCTYPE html>
  <html xmlns:th="http://www.thymeleaf.org">
  <head>
    <meta charset="UTF-8">
    <title>主页面</title>
    <!-- 引入资源片段 -->
    <th:block th:replace="~{fragments/common-header::common-header-imports}"></th:block>
  </head>
  <body>
    <!-- 引入导航片段 -->
    <th:block th:replace="~{fragments/common-header::common-header}"></th:block>
    
    <main>
      <h1>欢迎访问</h1>
    </main>
  </body>
  </html>
  

4. 查看服务器运行日志 #

• 启动服务后检查控制台日志，若存在TemplateInputException等异常，会直接提示模板找不到、解析错误等具体问题

5. 确认静态资源配置 #

• 若common-header-imports中引入了CSS/JS，需确保静态资源存放于src/main/resources/static目录，引用路径与文件位置对应（如/css/style.css对应static/css/style.css）

内容的提问来源于stack exchange，提问作者Nunyet Calçada