SpringBoot 3.0+Java17项目Thymeleaf依赖版本适配问题求助

1. 指定Thymeleaf 2.X.X版本出现404的原因 #

Spring Boot 3.0 对应的Thymeleaf适配版本为3.0+，2.x版本属于旧版，和Spring Boot 3依赖的Servlet API、视图解析逻辑完全不兼容，导致模板无法被正确识别渲染，最终返回404。

解决：直接弃用Thymeleaf 2.x版本，Spring Boot 3环境必须匹配Thymeleaf 3.x系列版本。

2. Thymeleaf 3.X.X及默认版本无法通过GraalVM运行的问题 #

核心原因 #

• 默认依赖的Thymeleaf starter虽宣称支持GraalVM，但缺少模板资源打包、方言组件初始化等原生镜像必需的配置，导致运行时无法加载关键资源。
• 手动指定3.x版本时，若版本与Spring Boot 3的依赖管理体系不匹配，会引发依赖冲突，破坏原生镜像的构建或运行逻辑。

分步解决 #

（1）依赖版本交给Spring Boot统一管理

删除所有手动指定的spring-boot-starter-thymeleaf、thymeleaf-layout-dialect版本号，让Spring Boot的依赖管理自动匹配兼容版本。Spring Boot 3.0+对应Thymeleaf 3.0.x系列，layout-dialect对应3.0.x版本，能从根源避免版本冲突。

（2）添加GraalVM原生镜像配置

在项目根目录创建src/main/resources/META-INF/native-image/你的项目组ID/你的项目 artifact ID/native-image.properties文件，写入以下配置：

# 确保Thymeleaf模板文件被打包进原生镜像
Args = -H:IncludeResources="templates/.*\\.html$"
# 启用HTTP/HTTPS协议支持
Args = -H:EnableURLProtocols=http,https
# 构建时初始化Thymeleaf核心引擎
Args = --initialize-at-build-time=org.thymeleaf.spring6.SpringTemplateEngine

（3）适配Thymeleaf Layout Dialect原生支持

如果使用布局方言，在上述native-image.properties中追加配置，确保方言组件在构建时完成初始化：

Args = --initialize-at-build-time=nz.net.ultraq.thymeleaf.layoutdialect.LayoutDialect

（4）使用Spring Boot官方原生镜像插件

确保构建文件中包含原生镜像构建插件：
Maven（pom.xml）：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <image>
            <builder>paketobuildpacks/builder-jammy-base:latest</builder>
        </image>
    </configuration>
</plugin>

Gradle（build.gradle）：

plugins {
    id 'org.springframework.boot' version '3.0.x'
    id 'io.spring.dependency-management' version '1.1.x'
    id 'java'
    id 'org.graalvm.buildtools.native' version '0.9.x'
}

执行构建命令生成原生镜像：

# Maven
./mvnw spring-boot:build-image
# Gradle
./gradlew bootBuildImage

3. 验证流程 #

1. 移除所有手动指定的Thymeleaf版本号
2. 添加上述原生镜像配置文件
3. 先启动常规JVM模式，确认http://localhost:8080/可正常访问
4. 构建并运行原生镜像，验证启动及页面访问正常

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