Spring Boot Thymeleaf 模板路径与视图解析问题详解

解决 Spring Boot 项目中因模板名称不匹配或路径配置错误导致的 Error resolving template [users] 500 错误，核心在于理解控制器返回的视图名、Thymeleaf 模板的物理位置以及 HTML 结构规范三者之间的协同关系。

在 Spring Boot + Thymeleaf 项目里，控制器方法返回的字符串（比如代码里写的 "users"）并不是一个文件名，也不是什么 URL 路径——它是一个逻辑视图名（view name）。Thymeleaf 的 TemplateResolver 会拿着这个名字去映射实际的文件路径。默认情况下，Spring Boot 自动配置的 Thymeleaf 会把视图名解析成 classpath:/templates/{viewName}.html。所以，问题就出在这里：

• 如果 @GetMapping("/") 返回的是 "users"，Thymeleaf 就会去加载 src/main/resources/templates/users.html；
• 但如果你只创建了 index.html，控制器却返回 "users"，那必然触发 TemplateInputException: Error resolving template [users]——这就是你遇到的那个典型错误。

如何解决 Spring Boot Thymeleaf 模板解析错误

要怎么解决？其实很简单，两个方案任选其一：

方案一：统一视图名与文件名

把 src/main/resources/templates/index.html 重命名为 users.html，控制器代码保持不动：

@GetMapping("/")
public String AllUsers(Model model) {
    model.addAttribute("listUsers", userService.getAllUsers());
    return "users"; // → 对应 users.html
}

方案二：修改控制器返回值，让它匹配现有文件

保留 index.html 不改名，把控制器返回值改成 "index"：

@GetMapping("/")
public String AllUsers(Model model) {
    model.addAttribute("listUsers", userService.getAllUsers());
    return "index"; // → 对应 index.html
}

Thymeleaf 模板规范与关键注意事项

哪怕路径对了，模板本身也得符合 Thymeleaf 规范，否则渲染还是会失败。这里有几个关键点需要注意：

• 用 th:each 遍历模型数据，别在页面里写一个空的 ；
• 属性绑定要用 th:text="${...}"，别硬编码原生 HTML 文本；
• 表格结构要完整—— 包裹 ， 里面用 ；
• WebJars 资源路径要以 / 开头，比如 th:href="@{/webjars/...}"，否则相对路径可能解析出错。

Spring Boot Thymeleaf 用户列表模板示例

这里给出一个修正后的 users.html 示例（推荐用这个命名，放在 templates/ 目录下）：

    
    
    



    

        

        

            
ID
            
Email
            
Name
            
Username
            
Password
            
Actions
        
        
        

        

            

            

            

            

            

            

                Edit
            
        
        
    



Spring Boot Thymeleaf 配置验证要点
最后再补充几个验证要点，免得踩坑：

确认 spring-boot-starter-thymeleaf 已经添加到 pom.xml 中；
检查 application.properties 里有没有意外禁用 Thymeleaf，比如 spring.thymeleaf.enabled=false；
确保 templates/ 目录位于 src/main/resources/ 下——注意，不是 src/main/webapp/ 或 static/；
如果用了 Lombok，确认 IDE 已经启用注解处理器，并且 User 类能正确生成 getter 方法（Thymeleaf 依赖反射调用 getEmail() 等）。

按照上面这些规范做完，访问 http://localhost:8080/ 就能顺利渲染用户列表页，模板解析异常的问题也就彻底解决了。