如何使用自定义TemplateEngine Bean？Spring Boot邮件启动Bean冲突排查

这个问题我之前也碰到过，核心原因很明确：你的Spring容器里现在存在两个TemplateEngine类型的Bean——一个是你自定义的，另一个是Spring Boot自动配置生成的默认Bean。当EmailService尝试注入htmlTemplateEngine字段时，Spring无法判断该选择哪一个，所以抛出了启动失败的错误。结合你想用自定义TemplateEngine替代默认Bean的需求，给你几个可行的解决方案：

方案1：给自定义Bean添加@Primary注解（推荐，最省事） #

通过@Primary注解标记你的自定义TemplateEngine，告诉Spring当存在多个同类型Bean时，优先使用这个标注的实例。这样自动配置的默认Bean就会被忽略，EmailService会自动注入你的自定义Bean。

示例代码：

@Configuration
public class ThymeleafConfig {
    @Bean
    @Primary // 关键：标记为优先选择的Bean
    public TemplateEngine customTemplateEngine() {
        SpringTemplateEngine templateEngine = new SpringTemplateEngine();
        // 配置你的模板解析器、方言等自定义逻辑
        templateEngine.setTemplateResolver(htmlTemplateResolver());
        return templateEngine;
    }

    private ITemplateResolver htmlTemplateResolver() {
        SpringResourceTemplateResolver resolver = new SpringResourceTemplateResolver();
        resolver.setPrefix("classpath:/templates/");
        resolver.setSuffix(".html");
        resolver.setTemplateMode(TemplateMode.HTML);
        resolver.setCharacterEncoding("UTF-8");
        return resolver;
    }
}

方案2：用@Qualifier指定要注入的Bean名称 #

如果之后你需要同时使用默认和自定义的TemplateEngine，可以给自定义Bean起一个唯一名称，然后在EmailService中通过@Qualifier指定要注入的Bean。

步骤1：给自定义Bean命名 #

@Configuration
public class ThymeleafConfig {
    @Bean("customHtmlTemplateEngine") // 给Bean设置唯一名称
    public TemplateEngine customTemplateEngine() {
        SpringTemplateEngine templateEngine = new SpringTemplateEngine();
        templateEngine.setTemplateResolver(htmlTemplateResolver());
        return templateEngine;
    }

    // 模板解析器配置...
}

步骤2：在EmailService中指定注入的Bean #

@Service
public class EmailService {
    private final TemplateEngine htmlTemplateEngine;

    // 构造注入时用@Qualifier指定Bean名称
    public EmailService(@Qualifier("customHtmlTemplateEngine") TemplateEngine htmlTemplateEngine) {
        this.htmlTemplateEngine = htmlTemplateEngine;
    }

    // 邮件发送逻辑...
}

方案3：禁用Spring Boot的Thymeleaf自动配置 #

如果你完全不需要默认的TemplateEngine，可以直接禁用Spring Boot的Thymeleaf自动配置，这样容器里只会有你自定义的Bean。

在启动类上添加exclude参数：

@SpringBootApplication(exclude = ThymeleafAutoConfiguration.class)
public class SpringMailApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringMailApplication.class, args);
    }
}

⚠️ 注意：禁用自动配置后，所有Thymeleaf相关的默认配置（比如模板解析器、标准方言）都需要你手动定义Bean，适合对Thymeleaf有完全自定义需求的场景。

另外还要提醒你：检查参考的thymeleafexamples-springmail示例代码，看看示例中的配置类（比如SpringMailConfig）是否也定义了TemplateEngine，如果有的话，要避免重复定义，建议合并到你的自定义配置中。

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