Keycloak自定义EmailTemplateProvider部分方法未生效问题咨询

1. 检查方法重载是否完整 #

确认你重写了EmailTemplateProvider接口中所有sendEvent相关的重载方法，比如：

@Override
public void sendEvent(Event event, UserModel user) {
    // 你的自定义实现
}

@Override
public void sendEvent(Event event, UserModel user, String clientId) {
    // 你的自定义实现
}

@Override
public void sendEvent(Event event, UserModel user, String clientId, URI redirectUri) {
    // 你的自定义实现
}

如果只重写了其中一个，其他重载方法会默认调用父类（默认实现）的逻辑，导致看起来没生效。

2. 验证SPI注册的正确性 #

• 确认jar包中META-INF/services/org.keycloak.email.EmailTemplateProvider文件的内容是你的自定义实现类的全限定类名，没有拼写错误。
• 检查打包后的jar，这个文件是否在正确的路径下，没有被其他依赖的同名文件覆盖（比如war包部署时，要确保WEB-INF/lib下你的jar里的这个文件是生效的）。
• 查看Keycloak启动日志，搜索EmailTemplateProvider相关的加载日志，确认你的自定义Provider被成功加载，而非默认的FreemarkerEmailTemplateProvider。

3. 检查Realm级别的配置 #

进入Keycloak管理控制台，查看对应Realm的Email配置：

• 确认该Realm没有单独指定使用默认的Email模板提供者。如果Realm级别的配置覆盖了全局默认，会导致该Realm下的邮件发送走默认实现。

4. 排查缓存与热部署问题 #

• 如果是热部署修改的Provider，Keycloak可能没有重新加载Provider实例，需要完全重启Keycloak服务后再测试。
• 清理Keycloak的缓存目录（比如standalone/data下的缓存文件），避免旧的Provider实例被缓存复用。

5. 跟踪调用路径（进阶） #

如果以上步骤都没问题，建议通过Debug跟踪：

• 在自定义Provider的sendEvent方法打断点，确认是否有进入；
• 查看调用sendEvent的上层代码，确认是否通过KeycloakSession.getProvider(EmailTemplateProvider.class)获取实例，而非直接实例化默认实现类。

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