Keycloak 4.0.0 Beta 2整合Spring Boot 2引入依赖后启动报错求助

这种类加载相关的错误我碰到过不少，结合你描述的“移除Keycloak依赖就能正常启动、Keycloak服务本身没问题”的情况，大概率是版本兼容性不匹配或者依赖配置错误导致的，下面给你具体的排查和解决步骤：

1. 优先检查Spring Boot与Keycloak Adapter的版本兼容性 #

这是最常见的坑！Keycloak的旧适配器（基于WildFly的keycloak-adapter-bom）和Spring Boot版本有严格的对应关系，尤其是Spring Boot 3.x之后，旧适配器完全不兼容——因为Spring Boot 3改用了Jakarta EE API，而旧适配器用的是javax API，会直接导致类冲突。

• 如果你的Spring Boot是2.x版本：
  确保引入的keycloak-adapter-bom版本和Spring Boot匹配，比如Spring Boot 2.7.x对应Keycloak Adapter 19.0.3~20.0.3，依赖配置要正确导入BOM：

  <dependencyManagement>
      <dependencies>
          <dependency>
              <groupId>org.keycloak.bom</groupId>
              <artifactId>keycloak-adapter-bom</artifactId>
              <version>19.0.3</version>
              <type>pom</type>
              <scope>import</scope>
          </dependency>
      </dependencies>
  </dependencyManagement>
  
  <dependencies>
      <dependency>
          <groupId>org.keycloak</groupId>
          <artifactId>keycloak-spring-boot-starter</artifactId>
      </dependency>
  </dependencies>
  

• 如果你的Spring Boot是3.x版本：
  旧的keycloak-adapter-bom已经废弃，必须使用新的Keycloak Spring Boot Starter（直接引入，不需要BOM），版本要对应Spring Boot 3.x，比如：

  <dependencies>
      <dependency>
          <groupId>org.keycloak</groupId>
          <artifactId>keycloak-spring-boot-starter</artifactId>
          <version>22.0.1</version> <!-- 适配Spring Boot 3.x -->
      </dependency>
  </dependencies>
  

2. 排查依赖冲突 #

用Maven或Gradle的依赖树命令查看是否有重复或冲突的依赖：

• Maven：执行 mvn dependency:tree，搜索spring-context、servlet-api等关键词，看是否有不同版本的Jar包共存，尤其是javax和jakarta开头的API冲突。
• 如果发现冲突，直接在依赖里排除掉旧版本的Jar包，比如排除javax.servlet的依赖：

  <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-spring-boot-starter</artifactId>
      <exclusions>
          <exclusion>
              <groupId>javax.servlet</groupId>
              <artifactId>javax.servlet-api</artifactId>
          </exclusion>
      </exclusions>
  </dependency>
  

3. 临时禁用JMX自动配置 #

报错里提到了org.springframework.boot.autoconfigure.jmx.Jm...，说明JMX自动配置和Keycloak适配器可能存在冲突，可以尝试禁用JMX来验证：

• 在application.properties中添加：

  spring.jmx.enabled=false
  

• 或者在启动类上排除JMX自动配置类：

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

4. 确保Keycloak基础配置完整 #

虽然你的报错是类加载问题，但如果缺少必要的Keycloak配置，也可能导致自动配置类初始化失败，确保application.properties/application.yml中有以下基础配置：

keycloak.realm=你的Realm名称
keycloak.auth-server-url=http://localhost:8080/auth
keycloak.resource=你的客户端ID
keycloak.credentials.secret=你的客户端密钥
keycloak.public-client=false

按照上面的步骤排查，90%以上的概率能解决这个问题，优先从版本兼容性入手，这是最容易踩的坑。

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