SpringBoot+Thymeleaf打jar包运行报模板解析错误如何排查解决

核心报错特征 #

IDEA本地启动无异常，打包为Jar运行时抛出如下错误：

org.thymeleaf.exceptions.TemplateInputException: Error resolving template [/login], template might not exist or might not be accessible by any of the configured Template Resolvers

该问题本质是本地开发环境的文件系统路径解析容错逻辑，和Jar包内嵌套类路径的严格匹配规则不一致导致，可按以下优先级排查修复：

• 修复视图路径写法（最高发诱因）
  检查Controller、拦截器、异常处理器等所有返回视图的逻辑，将模板路径前的前置斜杠删除，例如把return "/login"修改为return "login"。
  本地IDEA运行时，文件系统解析会自动容错路径中冗余的前置斜杠，但Jar包内的类路径资源匹配是严格字符串匹配，多余斜杠会导致最终拼接的模板路径无效。
• 校验模板资源是否被正确打入Jar包
  1. 确认所有Thymeleaf模板文件存放在src/main/resources/templates目录下，不要存放在webapp等Jar默认打包逻辑不会纳入的路径
  2. 如果自定义过Maven/Gradle的资源过滤规则，检查是否误排除了.html后缀文件，Maven默认正确的资源配置参考：

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <includes>
            <include>**/*</include>
        </includes>
    </resource>
</resources>

3. 打包完成后可解压Jar包，查看BOOT-INF/classes/templates路径下是否存在对应的login.html文件，若不存在则是打包环节遗漏了模板资源。

• 检查Thymeleaf配置合法性
  查看application.yml/application.properties中的Thymeleaf配置，不要使用本地磁盘绝对路径，类路径配置需注意前后斜杠规范，正确配置参考：

spring:
  thymeleaf:
    prefix: classpath:/templates/
    suffix: .html
    mode: HTML
    encoding: UTF-8
    cache: true

注意prefix配置的末尾必须携带斜杠，若写为classpath:/templates会导致路径拼接错误；如果本地调试时为了热更新配置过file:src/main/resources/templates/这类磁盘路径前缀，打Jar前必须改回类路径写法，Jar包内不存在源码目录结构，磁盘路径无法定位到嵌套资源。

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