Spring Boot 3.4升级后Thymeleaf报HtmlEscape类缺失错误

问题现象 #

应用启动成功，但访问登录页陷入重定向循环，控制台报错：

ERROR o.a.c.c.C.[.[.[.[dispatcherServlet] - Servlet.service() for servlet [dispatcherServlet] in context with path [/GFEPWeb] threw exception 
[Handler processing failed: java.lang.NoClassDefFoundError: org/unbescape/html/HtmlEscape]
 
Caused by: java.lang.ClassNotFoundException: org.unbescape.html.HtmlEscape
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521)

当前依赖配置（pom.xml） #

<dependency>
<groupId>org.thymeleaf</groupId>
<artifactId>thymeleaf</artifactId>
<version>3.1.2.RELEASE</version>
</dependency>
 
<dependency>
<groupId>org.unbescape</groupId>
<artifactId>unbescape</artifactId>
<version>1.1.6.RELEASE</version>
</dependency>

已尝试操作 #

• 确认thymeleaf和unbescape依赖已存在
• 清除浏览器缓存并重启服务器
• 验证依赖版本与Spring Boot 3.4兼容
• 检查thymeleaf-extras依赖

预期与实际行为 #

• 预期：登录页通过Thymeleaf正常渲染
• 实际：应用陷入重定向循环；日志出现org.unbescape.html.HtmlEscape的NoClassDefFoundError；移除所有Thymeleaf标签后页面可加载但无样式

环境信息 #

• Spring Boot版本: 3.4.0
• Java版本: 21
• Thymeleaf版本: 3.1.2.RELEASE
• Unbescape版本: 1.1.6.RELEASE
• Tomcat版本: 10.1.x（嵌入式）
• 依赖管理: Maven

问题解答 #

1. Thymeleaf 3.x是否仍使用org.unbescape.html.HtmlEscape，还是已被替代？ #

Thymeleaf 3.0.x系列确实依赖Unbescape的org.unbescape.html.HtmlEscape，但从Thymeleaf 3.1.0开始，已经把内部HTML转义实现切换到Java 11+自带的API，不再依赖这个类。如果你的代码、模板直接调用了这个类，或者有第三方依赖（比如旧版thymeleaf-extras）还在引用它，就会触发这个错误。

2. 是否需要显式引入unbescape依赖，还是Thymeleaf 3.x会内部管理？ #

Thymeleaf 3.1.x及以上核心包已经移除了对Unbescape的依赖，不需要显式引入。但如果项目里有其他组件（比如旧版Spring Security Thymeleaf集成、自定义标签库）还依赖Unbescape，可能需要保留，但建议把Unbescape升级到1.1.7.RELEASE（最后一个稳定版），避免和Java 21的类加载机制冲突。

3. 从1.5.x升级到3.4.x时是否遗漏了Thymeleaf迁移步骤？ #

是的，从Spring Boot 1.5（对应Thymeleaf 2.x）跳升到3.4（对应Thymeleaf 3.1.x）有几个关键迁移点容易漏：

• 依赖结构要换：Spring Boot 3.x里应该用spring-boot-starter-thymeleaf这个starter依赖，而不是直接引thymeleaf核心包。Starter会自动管理兼容的Thymeleaf版本及相关依赖，避免版本冲突。
• 模板语法要更新：Thymeleaf 3.x对语法做了不少调整，比如表达式规则、th:前缀的使用更严格，还移除了一些旧属性。如果登录页模板还用旧语法，会导致渲染失败，进而触发重定向循环（比如安全框架判断渲染失败后又重定向回登录页）。
• Servlet API兼容问题：Spring Boot 3.x基于Servlet 6.0，Tomcat 10.1.x用的是Jakarta EE API（包名从javax.servlet改成jakarta.servlet），如果自定义的Thymeleaf方言、过滤器还在引用旧的javax包，会引发类加载异常，间接导致渲染失败。
• 重定向循环的根源：大概率是登录页渲染失败后，被安全框架（比如Spring Security）重定向回登录页，形成闭环。先解决NoClassDefFoundError，再检查安全配置是否适配Spring Boot 3.x的规则。

修复建议 #

1. 替换依赖：删掉直接的thymeleaf和unbescape依赖，改用官方starter：

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

2. 清理模板：检查登录页Thymeleaf模板，移除或更新旧版语法，确保符合Thymeleaf 3.1.x规范。
3. 检查第三方依赖：如果用了thymeleaf-extras或Spring Security的Thymeleaf集成，确保版本适配Spring Boot 3.4（比如spring-boot-starter-security会自动管理对应的thymeleaf-extras-springsecurity版本）。
4. 排查依赖冲突：如果仍有NoClassDefFoundError，用mvn dependency:tree检查是否有旧版Unbescape被间接依赖，排除冲突的依赖。

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