Spring Thymeleaf二次生成PDF报TemplateEngine已初始化错误

开发者阿泽

2026-8-29

问题根因

报错和模板缓存无关，核心触发逻辑如下：

你通过@Autowired注入的TemplateEngine是Spring容器管理的单例Bean，Thymeleaf对TemplateEngine有明确的状态规则：实例首次执行模板渲染、或对外暴露完整Configuration配置对象后，会自动进入配置锁定状态，后续不允许对引擎配置做任何修改
你的代码把templateEngine.setTemplateResolver(templateResolver)写在了每次请求都会触发的processPdfTemplate方法内部：第一次调用方法时，引擎还未进入锁定状态，设置解析器、执行渲染的流程可以正常跑完，流程结束后引擎自动锁定配置；第二次调用时再次执行setTemplateResolver修改配置，就会直接抛出你看到的异常
clearTemplateCache()方法仅能清理已渲染完成的模板内容缓存，既不会解除引擎的配置锁定状态，也不会重置已写入的引擎配置，自然无法解决问题。

修复方案

优先选择全局统一配置的方案，不要在业务方法中修改TemplateEngine配置：

单独编写Thymeleaf配置类，全局只初始化一次模板解析器和PDF专用的模板引擎，避免重复修改配置

@Configuration
public class PdfThymeleafConfig {
    @Bean
    public ClassLoaderTemplateResolver pdfTemplateResolver() {
        ClassLoaderTemplateResolver templateResolver = new ClassLoaderTemplateResolver();
        templateResolver.setSuffix(".html");
        templateResolver.setTemplateMode(TemplateMode.HTML);
        templateResolver.setCharacterEncoding("UTF-8");
        // 可根据业务需要调整缓存策略，生产环境建议开启缓存提升性能
        templateResolver.setCacheable(true);
        return templateResolver;
    }

    @Bean
    public TemplateEngine pdfTemplateEngine() {
        TemplateEngine templateEngine = new TemplateEngine();
        templateEngine.setTemplateResolver(pdfTemplateResolver());
        return templateEngine;
    }
}

调整业务类代码，移除方法内部设置模板解析器的逻辑，直接注入提前配置好的专用模板引擎做渲染

@Service
public class LetterService {

    @Autowired
    @Qualifier("pdfTemplateEngine")
    private TemplateEngine pdfTemplateEngine;

    private String processPdfTemplate(Map<String, Object> variables) {
        Context context = new Context();
        context.setVariables(variables);
        context.setLocale(Locale.getDefault());
        return pdfTemplateEngine.process("index", context);
    }
}

如果有动态切换模板解析规则的特殊需求，每次渲染时新建全新的TemplateEngine实例即可，不要复用容器中已经初始化完成的单例引擎。注意这种方式每次都要重新初始化引擎，性能损耗较高，高并发场景不建议使用。

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