Mongock 5.x Spring Boot 3 兼容性配置指南

本文详解 mongock 5.x 在 spring boot 3 环境下启动失败（`could not find method getbuilder` / `required a bean of type connectiondriver`）的根本原因及正确依赖配置方案，重点适配 spring boot 3.x 的模块命名与自动装配机制。

在 Spring Boot 3.x 项目中集成 Mongock 5.x 时，若沿用官方文档中面向 Spring Boot 2.x 的依赖配置，极易触发以下典型错误：

Parameter 0 of method getBuilder in io.mongock.runner.springboot.config.MongockContext 
required a bean of type 'io.mongock.driver.api.driver.ConnectionDriver' that could not be found.

该异常并非配置遗漏或 Bean 定义缺失，而是由于 Mongock 5.x 对 Spring Boot 版本做了严格分包——其自动配置模块（如 mongock-springboot）已按 Spring Boot 大版本拆分为 mongock-springboot-v2 和 mongock-springboot-v3。使用 mongock-springboot（即 v2 版本）会导致 Spring Boot 3 的条件装配机制无法识别驱动类，进而无法注册 ConnectionDriver Bean，最终使 MongockContext.getBuilder() 方法因参数注入失败而启动中断。

✅ 正确的 Maven 依赖配置如下（以 Mongock 5.2.4 为例，推荐使用最新稳定版）：

  
    
      io.mongock
      mongock-bom
      5.2.4
      pom
      import
    
  



  
  
    io.mongock
    mongock-springboot-v3
  
  
  
    io.mongock
    mongodb-springdata-v4-driver
  
  
  
  

? 关键说明：

AI图像编辑器

使用文本提示编辑、变换和增强照片

下载

• mongock-bom 提供统一版本管理，避免各模块版本不一致；
• mongock-springboot-v3 是 Spring Boot 3 的唯一兼容入口模块，内含适配 ApplicationContextInitializer、AutoConfiguration 及 ConnectionDriver 自动注册逻辑；
• mongodb-springdata-v4-driver 对应 Spring Data MongoDB 4.x（Spring Boot 3 默认集成），确保 MongoTemplate/ReactiveMongoTemplate 正确注入并被 Mongock 驱动识别；
• @EnableMongock 注解仍需保留在主应用类上，但其生效前提完全依赖 mongock-springboot-v3 的自动配置。

配置文件（application.yml）保持不变，无需修改：

mongock:
  migration-scan-package: com.test.project.config.dbmigrations
  enabled: true

⚠️ 注意事项：

• 禁止混用 v2/v3 模块：例如同时引入 mongock-springboot 和 mongock-springboot-v3 将导致 Bean 冲突或条件装配失效；
• 驱动版本必须匹配：若项目实际使用 Spring Data MongoDB 3.x（极少见），则需降级为 mongodb-springdata-v3-driver + mongock-springboot-v2，但此组合不兼容 Spring Boot 3；
• 启用日志调试：添加 logging.level.io.mongock=DEBUG 可验证 ConnectionDriver 是否成功注册及迁移扫描路径是否正确加载。

完成上述调整后，应用将正常启动，Mongock 自动注册 ConnectionDriver Bean，并通过 MongockContext.getBuilder() 构建执行器，后续数据库迁移逻辑可按预期运行。