Thymeleaf模板th:href报错NoSuchMethodError求助

使用Thymeleaf 3.1.2.RELEASE + Spring5集成，设置th:href属性后模板渲染失败，抛出错误：

Caused by: java.lang.NoSuchMethodError: 'java.lang.String org.thymeleaf.util.ExpressionUtils.normalize(java.lang.String)'

移除th:href属性后错误消失，上下文已正确设置filesLink变量，相关配置如下：

依赖配置 #

<dependency>
    <groupId>org.thymeleaf</groupId>
    <artifactId>thymeleaf-spring5</artifactId>
    <version>3.1.2.RELEASE</version>
</dependency>
<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
</dependency>

Thymeleaf配置类 #

@Configuration
public class ThymeleafTemplateConfig
{
    @Bean
    public SpringTemplateEngine springTemplateEngine() {
        SpringTemplateEngine templateEngine = new SpringTemplateEngine();
        templateEngine.addTemplateResolver(htmlTemplateResolver());
        return templateEngine;
    }

    @Bean
    public ClassLoaderTemplateResolver htmlTemplateResolver(){
        ClassLoaderTemplateResolver emailTemplateResolver = new ClassLoaderTemplateResolver();
        emailTemplateResolver.setPrefix("templates/");
        emailTemplateResolver.setSuffix(".html");
        emailTemplateResolver.setTemplateMode(TemplateMode.HTML);
        emailTemplateResolver.setCharacterEncoding(StandardCharsets.UTF_8.name());
        return emailTemplateResolver;
    }
}

邮件服务类 #

@Service
@RequiredArgsConstructor
public class EmailService {

    private final SpringTemplateEngine templateEngine;

    protected String createSummaryEmailBody(RunEntity runEntity, String filesLink) {
        Context context = new Context();
        context.setVariable("year", runEntity.getFinancialYear());
        context.setVariable("period", runEntity.getFinancialPeriod());
        context.setVariable("filesLink", filesLink);
        return templateEngine.process("summary-report", context);
    }
}

模板文件summary-report.html #

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Report Summary</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            margin: 0;
            padding: 0;
        }
        table {
            width: 100%;
            border-collapse: collapse;
            margin-top: 20px;
        }
        th, td {
            border: 1px solid #ddd;
            padding: 8px;
            text-align: left;
        }
        th {
            background-color: #f2f2f2;
        }
        .link {
            color: #007bff;
            text-decoration: none;
        }
    </style>
</head>
<body>
<div>
    <h1>Report Summary</h1>
    <p><strong>Year:</strong> <span th:text="${year}"></span></p>
    <p><strong>Period:</strong> <span th:text="${period}"></span></p>
    <p>Files are ready to view <a class="link" th:href="${filesLink}" target="_blank">here</a>.</p>
</div>
</body>
</html>

原因分析 #

这个错误是thymeleaf-layout-dialect版本与Thymeleaf 3.1.x不兼容导致的：

• Thymeleaf 3.1.x中移除了org.thymeleaf.util.ExpressionUtils.normalize()方法
• 未指定版本的layout-dialect会默认拉取旧版本（3.1.x及以下），这些版本依然依赖已被移除的方法
• 模板中存在th:href时，layout方言的链接处理器会触发调用该方法，从而抛出异常；移除该属性则不会触发对应处理器，因此错误消失

解决方法 #

1. 指定兼容的layout-dialect版本 #

给thymeleaf-layout-dialect添加与Thymeleaf 3.1.x匹配的版本号，推荐使用3.2.0及以上版本（该版本开始支持Thymeleaf 3.1.x）：

<dependency>
    <groupId>org.thymeleaf</groupId>
    <artifactId>thymeleaf-spring5</artifactId>
    <version>3.1.2.RELEASE</version>
</dependency>
<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
    <version>3.2.0</version> <!-- 与Thymeleaf 3.1.x兼容 -->
</dependency>

2. 验证依赖树（可选） #

执行Maven命令检查依赖树，确保没有冲突的Thymeleaf核心包：

mvn dependency:tree

如果发现旧版本thymeleaf-core被间接依赖，可在layout-dialect依赖中添加排除：

<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
    <version>3.2.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.thymeleaf</groupId>
            <artifactId>thymeleaf</artifactId>
        </exclusion>
    </exclusions>
</dependency>

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