Spring Boot + Thymeleaf项目运行出现空白页问题求助

安全阿岳

2026-6-17

Spring Boot + Thymeleaf 页面空白问题排查与解决

问题背景

用Spring Boot Initializr创建了基于HTML和Bootstrap的Tech Shop项目，运行后页面显示空白。尝试过修改端口、更换JDK版本（17→23）、切换Spring Boot版本（3.1.0→3.3.4）、升级依赖，问题仍未解决。服务器和浏览器控制台均无报错信息，换电脑或新建相同布局的项目也出现同样问题，怀疑路径配置存在问题但无法确定根本原因。

相关代码片段

pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.4</version>
    <relativePath/>
</parent>
<groupId>Tienda</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>Tienda</name>
<description>Demo project for Spring Boot</description>
<url/>
<licenses>
    <license/>
</licenses>
<developers>
    <developer/>
</developers>
<scm>
    <connection/>
    <developerConnection/>
    <tag/>
    <url/>
</scm>
<properties>
    <java.version>21</java.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>5.3.1</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>font-awesome</artifactId>
        <version>6.4.0</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>jquery</artifactId>
        <version>3.7.0</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>popper.js</artifactId>
        <version>2.11.7</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>webjars-locator</artifactId>
        <version>0.47</version>
    </dependency>
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>
</project>

index.html

<html xmlns:th="http://www.thymeleaf.org"
      xmlns="http://www.w3.org/1999/xhtml">
    <head th:replace="~{layout/plantilla :: head}">
        <title>TechShop</title>
            </head>
    <body>
        <header th:replace="~{layout/plantilla :: header}"/>
        
        <footer th:replace="~{layout/plantilla :: footer}"/>
              </body>
</html>

layout.html

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:th="http://www.thymeleaf.org">
    <head th:fragment="head">
        <title>TechShop</title>
        <meta charset="UTF-8"/>
        <link th:href="@{/webjars/bootstrap/css/bootstrap.min.css}" rel="stylesheet"/>
        <link th:href="@{/webjars/font-awesome/css/all.css}" rel="stylesheet"/>
        <script th:src="@{/webjars/jquery/jquery.min.js}"></script>
        <script th:src="@{/webjars/popper.js/umd/popper.min.js}"></script>
        <script th:src="@{/webjars/bootstrap/js/bootstrap.min.js}"></script>
            </head>
    <body>
        <header th:fragment="header" class="header">
            <nav class="navbar navbar-expand-sm navbar-dark bg-dark p-0">
                <div class="container">
                    <a th:href="@{/}" class="navbar-brand">[[#{aplicacion.titulo}]]</a>
                    <button class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbarCollapse">
                        <span class="navbar-toggler-icon"></span>
                    </button>
                    <div class="collapse navbar-collapse justify-content-between" id="navbarCollapse">
                        <ul class="navbar-nav">
                            <li class="nav-item px-2"><a class="nav-menu-link nav-link" th:href="@{/categoria/listado}">[[#{plantilla.categorias}]]</a></li>
                            <li class="nav-item px-2"><a class="nav-menu-link nav-link" th:href="@{/producto/listado}">[[#{plantilla.productos}]]</a></li>
                            <li class="nav-item px-2"><a class="nav-menu-link nav-link" th:href="@{/usuario/listado}">[[#{plantilla.usuarios}]]</a></li>
                        </ul>
                        <div class="col-md-3">
                            <ul class="navbar-nav">
                                                                <li class="nav-item px-2"><a class="nav-link" th:href="@{/(lang=es)}">ES</a></li>
                                <li class="nav-item px-2"><a class="nav-link" th:href="@{/(lang=en)}">EN</a></li>
                            </ul>
                        </div>
                    </div>
                </div>
            </nav>
            <section id="main-header" class="py-2 bg-success text-white">
                <div class="container">
                    <div class="row">
                        <div class="col-md-6">
                            <h1><i class="fas fa-cog"></i> [[#{plantilla.suTienda}]]</h1>
                        </div>
                    </div>
                </div>
            </section>
        </header>
        <footer th:fragment="footer" class="bg-info text-white mt-5 p-2">
            <div class="container">
                <div class="col">
                    <p class="lead text-center">
                        &COPY [[#{plantilla.derechos}]]
                    </p>
                </div>
            </div>
        </footer>
    </body>
</html>

排查与解决步骤

1. 核对模板文件路径

Thymeleaf默认从src/main/resources/templates目录加载模板，确保文件结构完全匹配：

src/main/resources/
└── templates/
    ├── index.html
    └── layout/
        └── plantilla.html

如果路径不对，模板无法被加载，页面自然空白。

2. 补全国际化配置文件

页面中使用了[[#{aplicacion.titulo}]]这类国际化表达式，若缺少对应的配置文件，Thymeleaf会输出空字符串，导致页面内容缺失。在src/main/resources下创建以下文件：

messages_es.properties（西班牙语）

aplicacion.titulo=TechShop
plantilla.categorias=Categorías
plantilla.productos=Productos
plantilla.usuarios=Usuarios
plantilla.suTienda=Tu Tienda de Tecnología
plantilla.derechos=Todos los derechos reservados 2024

messages_en.properties（英语）

aplicacion.titulo=TechShop
plantilla.categorias=Categories
plantilla.productos=Products
plantilla.usuarios=Users
plantilla.suTienda=Your Tech Shop
plantilla.derechos=All Rights Reserved 2024

messages.properties（默认 fallback）：可复制任意语言版本内容。

3. 添加根路径映射控制器

确保存在控制器类将根路径/映射到index视图：

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {

    @GetMapping("/")
    public String home() {
        return "index";
    }
}

没有这个控制器，Spring Boot无法找到对应的视图，会返回空白页面。

4. 开启Thymeleaf调试日志

在application.properties中添加配置，查看模板加载和解析的详细日志：

logging.level.org.thymeleaf=DEBUG
logging.level.org.springframework.web.servlet=DEBUG

启动项目后，通过控制台日志确认模板是否被正确加载、片段是否被正常替换。

5. 测试静态内容渲染

临时在index.html的<body>中添加静态内容：

<body>
    <h1>测试内容</h1>
    <header th:replace="~{layout/plantilla :: header}"/>
    <footer th:replace="~{layout/plantilla :: footer}"/>
</body>

如果静态内容能显示，说明问题出在片段替换或国际化配置上；若仍空白，需检查Thymeleaf引擎的基础配置。

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

Spring Boot + Thymeleaf项目运行出现空白页问题求助

问题背景 #

相关代码片段 #

pom.xml

index.html

layout.html

排查与解决步骤 #

1. 核对模板文件路径 #

2. 补全国际化配置文件 #

3. 添加根路径映射控制器 #

4. 开启Thymeleaf调试日志 #

5. 测试静态内容渲染 #