Spring Boot 3中Thymeleaf模板未渲染问题排查求助

环境信息 #

• Spring Boot 3.0.0
• Thymeleaf依赖：thymeleaf-spring6 3.1.0.RELEASE

模板文件（classpath:/templates/plans/test.html） #

<!doctype html>
<html lang="pl">
<div th:text="${loki}"></div>
</html>

渲染代码 #

@RestController
public class PlansPageRestController {

    @Autowired
    TemplateEngine myTemplateEngine;

    @RequestMapping(value = {"/public/plans"}, method = RequestMethod.POST, produces = "application/json")
    public Map<String,String> getPlans(@RequestParam Map<String, String> requestParams) {

        Context ctx = new Context();
        ctx.setVariable("loki", "Some test value");

        String htmlTemplate = myTemplateEngine.process("plans/test.html", ctx);

        Map<String,String> result = new HashMap<>();
        result.put("html", htmlTemplate );
        result.put("result", "success" );

        return result;
    }

}

Thymeleaf配置类 #

@Configuration
public class ThymeleafConfiguration implements WebMvcConfigurer, ApplicationContextAware {

    private ApplicationContext applicationContext;

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        this.applicationContext = applicationContext;
    }

    @Bean
    public TemplateEngine myTemplateEngine() {
        SpringTemplateEngine engine = new SpringTemplateEngine();
        engine.setEnableSpringELCompiler(true);
        engine.setTemplateResolver(templateResolver());
        engine.setDialect(new LayoutDialect());
        return engine;
    }
    private ITemplateResolver templateResolver() {
        SpringResourceTemplateResolver resolver = new SpringResourceTemplateResolver();
        resolver.setApplicationContext(applicationContext);
        resolver.setPrefix("classpath:/templates/");
        resolver.setTemplateMode(TemplateMode.HTML);
        resolver.setCacheable(false);
        resolver.setCacheTTLMs(0L);
        resolver.setCharacterEncoding("UTF-8");
        return resolver;
    }
}

问题现象 #

调用接口后返回的html字段内容为模板原始代码，th:text="${loki}"未被替换为指定的Some test value。

1. 注册Thymeleaf核心方言 #

自定义的TemplateEngine仅添加了LayoutDialect，但解析th:*属性的核心StandardDialect未注册，这是模板无法渲染的关键原因。修改配置类中的模板引擎初始化方法：

@Bean
public TemplateEngine myTemplateEngine() {
    SpringTemplateEngine engine = new SpringTemplateEngine();
    engine.setEnableSpringELCompiler(true);
    engine.setTemplateResolver(templateResolver());
    // 添加核心StandardDialect
    engine.addDialect(new StandardDialect());
    engine.addDialect(new LayoutDialect());
    return engine;
}

注意用addDialect而非setDialect，避免覆盖已添加的方言。

2. 明确指定注入的Bean #

确保注入的是自定义的myTemplateEngine，而非Spring Boot自动配置的默认实例，添加@Qualifier注解：

@Autowired
@Qualifier("myTemplateEngine")
TemplateEngine myTemplateEngine;

3. 验证模板路径 #

确认plans/test.html确实位于src/main/resources/templates/目录下，路径与配置的prefix（classpath:/templates/）完全匹配，注意文件名大小写敏感。

4. 清理缓存（可选） #

虽然已关闭缓存，但可清理项目target目录后重新构建，避免旧缓存文件干扰结果。

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