SpringBoot无法识别Thymeleaf模板问题求助

云原生阿岚

2026-8-12

SpringBoot整合Thymeleaf模板无法识别问题排查

我刚开始学习SpringBoot整合Thymeleaf模板，遇到一个难排查的隐性问题——SpringBoot应用无法识别Thymeleaf模板。已满足以下条件：

控制器代码按规范编写，返回视图名称"home"
项目结构包含/templates目录，模板文件存放其中
已配置Thymeleaf相关依赖

访问http://localhost:8081/home时仅返回"home"字符串，Spring Boot启动日志如下：

2022-11-13 22:21:13.196  INFO 20644 --- [           main] com.coffeeshop.Application               : Starting Application using Java 11.0.10 on LAPTOP-O6B9USVI with PID 20644 (C:\Dev\Java\Projects\coffeeshop\build\classes\java\main started by User in C:\Dev\Java\Projects\coffeeshop)
2022-11-13 22:21:13.196  INFO 20644 --- [           main] com.coffeeshop.Application               : No active profile set, falling back to 1 default profile: "default"
2022-11-13 22:21:13.588  INFO 20644 --- [           main] .s.d.r.c.RepositoryConfigurationDelegate : Bootstrapping Spring Data JPA repositories in DEFAULT mode.
2022-11-13 22:21:13.604  INFO 20644 --- [           main] .s.d.r.c.RepositoryConfigurationDelegate : Finished Spring Data repository scanning in 23 ms. Found 1 JPA repository interfaces.
2022-11-13 22:21:14.106  INFO 20644 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8081 (http)
2022-11-13 22:21:14.106  INFO 20644 --- [main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-11-13 22:21:14.106  INFO 20644 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.64]
2022-11-13 22:21:14.184  INFO 20644 --- [main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-11-13 22:21:14.184  INFO 20644 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 957 ms
2022-11-13 22:21:14.278  INFO 20644 --- [           main] o.hibernate.jpa.internal.util.LogHelper  : HHH000204: Processing PersistenceUnitInfo [name: default]
2022-11-13 22:21:14.309  INFO 20644 --- [           main] org.hibernate.Version                    : HHH000412: Hibernate ORM core version 5.6.9.Final
2022-11-13 22:21:14.309  INFO 20644 --- [           main] org.hibernate.cfg.Environment            : HHH000205: Loaded properties from resource hibernate.properties: {hibernate.temp.use_jdbc_metadata_defaults=false, hibernate.bytecode.use_reflection_optimizer=false}
2022-11-13 22:21:14.404  INFO 20644 --- [           main] o.hibernate.annotations.common.Version   : HCANN000001: Hibernate Commons Annotations {5.1.2.Final}
2022-11-13 22:21:14.466  INFO 20644 --- [           main] org.hibernate.dialect.Dialect            : HHH000400: Using dialect: org.hibernate.dialect.PostgreSQLDialect
2022-11-13 22:21:14.796  INFO 20644 --- [           main] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Starting...
2022-11-13 22:21:14.905  INFO 20644 --- [           main] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Start completed.
2022-11-13 22:21:14.921  INFO 20644 --- [           main] o.h.e.t.j.p.i.JtaPlatformInitiator       : HHH000490: Using JtaPlatform implementation: [org.hibernate.engine.transaction.jta.platform.internal.NoJtaPlatform]
2022-11-13 22:21:14.921  INFO 20644 --- [           main] j.LocalContainerEntityManagerFactoryBean : Initialized JPA EntityManagerFactory for persistence unit 'default'
2022-11-13 22:21:15.094  WARN 20644 --- [           main] JpaBaseConfiguration$JpaWebConfiguration : spring.jpa.open-in-view is enabled by default. Therefore, database queries may be performed during view rendering. Explicitly configure spring.jpa.open-in-view to disable this warning
2022-11-13 22:21:15.298  INFO 20644 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8081 (http) with context path ''
2022-11-13 22:21:15.298 INFO 20644 --- [           main] com.coffeeshop.Application: Started Application in 2.409 seconds (JVM running for 2.7)

问题原因及解决方案

返回字符串"home"而非渲染模板，核心是Spring未将请求映射到Thymeleaf视图解析器，直接返回了字符串。按以下步骤排查：

检查控制器注解
确保控制器类使用@Controller，而非@RestController。@RestController会强制所有返回值以JSON/字符串格式响应，不会触发视图解析。若需保留@RestController，可在返回视图的方法中返回ModelAndView对象来指定模板。
确认Thymeleaf依赖正确引入
Maven项目需在pom.xml中添加：
```
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
```
Gradle项目需在build.gradle中添加：
```
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
```
从启动日志看，无Thymeleaf初始化相关输出，大概率是依赖未正确引入或未生效，可重新同步依赖并重启项目。
验证模板文件位置与命名
确保模板文件（如home.html）存放在src/main/resources/templates目录下，文件名大小写与控制器返回的视图名称完全一致（SpringBoot默认大小写敏感）。
检查Thymeleaf默认配置
SpringBoot默认配置无需手动修改，若自定义了配置，需确保：
```
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html
spring.thymeleaf.enabled=true
```
这些参数保证视图解析器能正确定位模板文件。
确认启动类扫描范围
启动类@SpringBootApplication的包扫描范围需覆盖控制器所在包，若控制器在启动类的子包外，需手动添加@ComponentScan指定扫描路径。

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

SpringBoot无法识别Thymeleaf模板问题求助

问题原因及解决方案 #

问题原因及解决方案