Thymeleaf打包为Jar后无法识别页面模板问题排查与解决

使用Java 17 + Maven 3.2.0 + Thymeleaf 3.1.1.RELEASE开发Spring Boot 3.2.0项目时，IDEA本地运行一切正常，但通过Maven打包成Jar文件后，Thymeleaf无法找到页面模板。

项目配置信息 #

pom.xml核心依赖 #

<parent>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-parent</artifactId>
   <version>3.2.0</version>
   <relativePath/>
</parent>

<properties>
   <java.version>17</java.version>
</properties>

<dependencies>
     <dependency>
        <groupId>org.thymeleaf.extras</groupId>
            <artifactId>thymeleaf-extras-springsecurity6</artifactId>
            <version>3.1.1.RELEASE</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>

        <!--Security-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
            <version>2.2.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.33</version>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.modelmapper</groupId>
            <artifactId>modelmapper</artifactId>
            <version>3.1.1</version>
        </dependency>

        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.10.1</version>
            <scope>test</scope>
    </dependency>
</dependencies>

注：原配置中存在重复的thymeleaf-extras-springsecurity6依赖，已移除重复项

application.properties配置 #

#ThymeLeaf Edit
spring.thymeleaf.cache=false
spring.thymeleaf.prefix=classpath:/templates/
spring.web.resources.static-locations=classpath:/static/
spring.web.resources.cache.period=0

项目目录结构 #

src
└── main
    ├── java
    │   └── com
    │       └── example
    │           └── Application.java
    └── resources
        ├── static
        │   ├── assets
        │   │   └── css
        │   │       └── style.css
        │   └── images
        │       └── logo
        │           └── logo-dark.png
        └── templates
            ├── blocks
            │   ├── footer.html
            │   ├── header.html
            │   └── sidebar.html
            ├── admin
            │   └── products
            │       └── add.html
            └── index.html

排查与解决步骤 #

1. 检查打包后的Jar文件，确认内部文件结构与本地一致，模板文件已正确打入Jar包。
2. 查看运行日志，定位到Thymeleaf模板解析错误，问题根源在于th:insert的语法使用错误。

原错误语法示例：

<div th:insert="~{/blocks/sidebar :: sidebar}"></div>

将{后的斜杠移除，修改为正确的相对路径引用语法：

<div th:insert="~{blocks/sidebar :: sidebar}"></div>

修改后重新打包运行，Thymeleaf即可正常加载模板文件。

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