嵌入式Keycloak应用已存自定义主题文件仍抛出FreeMarkerException

在独立版Keycloak中正常运行的自定义登录主题，嵌入Spring应用（Keycloak 17.0.1 + Spring 2.6.7）时，FreeMarkerUtil抛出FreeMarkerException提示主题不存在。已按官方及教程将主题文件放在themes/<myTheme>/路径，并通过System.property配置路径，但问题依旧。

以下是针对性的排查和解决步骤：

• 显式配置主题加载路径
  嵌入式Keycloak的主题读取逻辑与独立版不同，全局System.property配置可能不生效，建议通过Keycloak配置类指定classpath路径：

  @Bean
  public KeycloakServerProperties keycloakServerProperties() {
      KeycloakServerProperties properties = new KeycloakServerProperties();
      KeycloakServerProperties.Theme themeConfig = new KeycloakServerProperties.Theme();
      themeConfig.setDirs(Collections.singletonList("classpath:themes"));
      properties.setTheme(themeConfig);
      return properties;
  }
  

  确保themes目录放在src/main/resources下，打包后自动纳入classpath。

• 校验主题目录结构合规性
  自定义主题必须严格遵循Keycloak目录规范，登录主题示例结构：

  themes/<myTheme>/
    ├── login/
    │   ├── ftl/
    │   │   ├── login.ftl
    │   │   └── 其他模板文件
    │   ├── theme.properties
    │   └── messages/
    │       └── messages_en.properties
    └── theme.properties
  

  根目录theme.properties需声明继承关系：

  parent=keycloak
  import=common/login
  

  登录模块下的theme.properties指定模板配置：

  template.login=login.ftl
  styles=css/login.css
  

• 查看主题加载日志
  开启Keycloak的DEBUG日志，搜索ThemeManager相关记录，确认启动时是否扫描到<myTheme>。若未出现加载日志，说明路径或结构存在问题。

• 禁用绝对路径配置
  嵌入式环境下绝对路径易因部署环境变化失效，优先使用classpath相对路径，确保主题资源随应用包分发。

• 在控制台启用主题
  启动嵌入式Keycloak后，登录管理控制台，进入目标Realm的「主题」设置，将登录主题选择为<myTheme>并保存，再测试登录流程。

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