Spring Boot+Thymeleaf控制器返回模板名未渲染页面求助

使用Java、Spring Boot和Thymeleaf开发时，点击页面按钮本应获取数据并渲染模板，但浏览器空白页仅显示模板名称all-families。另一套结构完全相同的控制器和模板（用于其他对象）可正常工作。

相关代码 #

控制器代码 #

控制器类路径为/family，对应方法：

@GetMapping("/all")
public String getFamilyList(Model model) {
    List<Family> list = familyService.getAllFamilies();
    model.addAttribute("families", list);
    return "all-families";
}

触发请求的按钮代码 #

<a th:href="@{/family/all}" class="btn btn-success">Family list</a>

all-families模板代码 #

<!DOCTYPE html>
<html lang="en" xmlns:th="http://thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>List of all families</title>
<link rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/bootstrap@4.3.1/dist/css/bootstrap.min.css"
    integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T"
    crossorigin="anonymous">
<link rel="stylesheet" th:href="@{/css/main.css}" />
</head>

<body>
    <div class="navbar navbar-expand-lg static-top">
        <a class="navbar-brand" href="/"> <span class="sr-only">(current)</span>
            <img th:src="@{/images/plantIcon.png}" alt="..." height="36" />
        </a>
        <div class="collapse navbar-collapse" id="navbarSupportedContent">
            <ul class="navbar-nav ms-auto">
                <li class="nav-item">
                    <a class="nav-link" href="/">Home<span class="sr-only">(current)</span></a>
                </li>
                <li class="nav-item">
                    <a class="nav-link" href="/herbarium/all/user">Herbarium</a>
                </li>
                <li class="nav-item">
                    <a class="nav-link" href="/userLists/user/{id}(id=${current.userId})">Lists</a>
                </li>
                <li class="nav-item">
                    <a class="nav-link" href="/family/search">Find</a>
                </li>
            </ul>
        </div>
    </div>

    <div class="container">
        <a th:href="@{/family}" class="btn btn-success">Add Family</a>
        <br></br>
        <table class="table">
            <thead>
                <tr>
                    <th scope="col">Name</th>
                    <th scope="col">Info link</th>
                    <th scope="col" colspan="2"></th>
                </tr>
            </thead>
            <tbody>
                <tr th:each="family: ${families}">
                    <td th:text="${family.name}"></td>
                    <td th:text="${family.link}"></td>
                    <td>
                        <a th:href="@{/family/update/{id}(id=${family.familyId})}" class="btn btn-info">Update family</a>
                    </td>
                    <td>
                        <a th:href="@{/family/delete/{id}(id=${family.familyId})}" class="btn btn-danger">Delete family</a>
                    </td>
                </tr>
            </tbody>
        </table>
    </div>

    <footer id="sticky-footer" class="flex-shrink-0 py-4 text-white-50">
        <div>
            <small>Copyright &copy; Online Herbarium</small>
        </div>
    </footer>
    <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js"
        integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo"
        crossorigin="anonymous"></script>
    <script
        src="https://cdn.jsdelivr.net/npm/popper.js@1.14.7/dist/umd/popper.min.js"
        integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1"
        crossorigin="anonymous"></script>
    <script
        src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/js/bootstrap.min.js"
        integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM"
        crossorigin="anonymous"></script>
    <script
        src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css"
        integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM"
        crossorigin="anonymous"></script>
</body>
</html>

排查与解决建议 #

1. 修正Thymeleaf命名空间
   模板中的Thymeleaf命名空间缺失www，正确写法应为：

   xmlns:th="http://www.thymeleaf.org"
   

   这是最可能导致模板无法解析的原因。

2. 检查模板文件位置
   确认all-families.html放在Thymeleaf默认目录src/main/resources/templates/下，若在子目录，返回值需加上前缀（如"families/all-families"）。

3. 验证控制器注解
   确保控制器类标注@Controller而非@RestController——后者会直接返回字符串，不会触发模板渲染。

4. 排查模板语法错误

   • 检查th:each循环中的变量名是否与控制器传入的families一致
   • 确认Family类中存在name、link、familyId属性及对应getter方法

5. 查看日志定位异常
   在application.properties中开启DEBUG日志，查看模板解析或数据加载报错：

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

6. 对比正常模板差异
   将当前模板与其他正常工作的模板逐一对比，检查文件名大小写、静态资源引用、表达式写法是否一致。

内容的提问来源于stack exchange，提问作者Deni Bakulić