团队协作中，数据库版本混乱是常见痛点：本地改表结构未同步脚本、部署时报SQL异常、变更历史无法追溯，而Flyway能完美解决这些问题。它轻量无侵入，与SpringBoot3集成后，项目启动即可自动同步数据库脚本，无需手动操作，轻松实现数据库版本规范化管理。

一、Flyway核心作用

Flyway的核心是将数据库脚本按版本管理，项目启动时自动执行未执行的脚本，并记录所有变更历史，解决以下痛点：

1. 多人协作脚本散落，易漏执行、错执行；

2. 部署时忘记同步脚本，导致项目启动失败；

3. 数据库结构迭代后，变更历史无法追溯；

4. 手动回滚易误操作删错数据。

补充：Flyway比Liquibase更轻量、SQL原生支持，适合常规SpringBoot+MySQL项目；Liquibase功能更全但配置复杂，适合跨数据库场景。

二、环境准备

推荐适配版本（亲测无兼容问题），避免踩版本坑：

- SpringBoot：3.2.4（企业级稳定版）

- Flyway：10.22.0（与SpringBoot3.2.x完美适配）

- 数据库：MySQL 8.0（5.7通用）

- 构建工具：Maven（Gradle步骤见下文补充）

注意：SpringBoot3强制依赖JDK17，需确保本地JDK≥17；Flyway与SpringBoot3版本必须匹配，3.2.x不可用Flyway9.x及以下。

三、SpringBoot3集成Flyway实操步骤

第一步：引入依赖（Maven）

SpringBoot3已自带Flyway自动配置，只需引入Flyway核心依赖、flyway-mysql依赖，同时手动添加MySQL驱动和JDBC依赖（SpringBoot3默认移除这两个依赖，缺一不可）。

<!-- Flyway核心依赖 -->    org.flywaydb    flyway-core    10.22.0<!-- Flyway mysql依赖 -->    org.flywaydb    flyway-mysql    10.22.0<!-- MySQL驱动 -->    com.mysql    mysql-connector-j    runtime<!-- JDBC依赖（必加，否则无法获取数据源） -->    org.springframework.boot    spring-boot-starter-jdbc

第二步：配置application.yml

添加数据库和Flyway核心配置，多余配置按项目实际调整：

spring:  datasource:    url: jdbc:mysql://localhost:3306/flyway_demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true    username: root    password: 123456    driver-class-name: com.mysql.cj.jdbc.Driver  flyway:    enabled: true # 开启Flyway（默认true）    baseline-on-migrate: true # 非空库自动创建基线版本    baseline-version: 0 # 基线版本，后续脚本从1开始    locations: classpath:db/migration # 脚本存放路径    encoding: UTF-8    clean-disabled: true # 生产环境必设true，禁止误删表    validate-on-migrate: true # 迁移前校验脚本    out-of-order: false # 禁止乱序执行脚本    enabled-profiles: prod # 可选，指定生效环境

核心配置说明：

1. baseline-on-migrate: true：非空库必开，自动创建版本历史表；

2. clean-disabled: true：生产环境禁用clean命令，防止误删数据；

3. out-of-order: false：强制脚本按版本递增执行。

第三步：编写SQL脚本（命名规范是关键）

1. 创建脚本目录：src/main/resources/db/migration（与配置一致）；

2. 命名规范（记死）：V{版本号}__{脚本描述}.sql（两个下划线，不可修改）；

正确示例：V1__init_user_table.sql、V2__add_age_column_to_user.sql；

错误示例：V1_init_user_table.sql（少一个下划线）、1__init_user_table.sql（少V前缀）。

脚本示例（V1__init_user_table.sql）：

-- 初始化系统用户表CREATE TABLE IF NOT EXISTS `sys_user` (  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',  `username` VARCHAR(50) NOT NULL COMMENT '用户名',  `password` VARCHAR(100) NOT NULL COMMENT '加密密码',  `nickname` VARCHAR(50) DEFAULT '' COMMENT '昵称',  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,  PRIMARY KEY (`id`),  UNIQUE KEY `uk_username` (`username`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户表';-- 测试环境初始化管理员（生产可删除）INSERT INTO `sys_user` (`username`, `password`, `nickname`) VALUES ('admin', '123456', '超级管理员');

文件放置示意图：

第四步：启动项目，验证效果

启动SpringBoot3项目（确保JDK≥17），Flyway会自动执行脚本，可通过日志和数据库两方面验证集成效果：

1. 日志验证：开启DEBUG日志（logging.level.org.flywaydb: DEBUG），出现“Successfully applied 1 migration”即为成功；

2. 数据库验证：自动生成flyway_schema_history（版本历史表）和sys_user（脚本创建表）。

成功示意图如下：

四、易出错点提前规避

易出错点1：脚本命名不规范，导致脚本无法执行

现象：项目启动无报错，但脚本未执行、数据库无对应表结构；原因：未遵循V{版本号}__{描述}.sql的命名格式，Flyway无法识别脚本；解决方案：严格按规范命名，确保V前缀、两个下划线齐全，版本号递增，描述无空格。

易出错点2：非空库集成，启动报错“找不到基线版本”

现象：非空库集成Flyway时，启动报错“Schema history table 'flyway_schema_history' does not exist”；原因：未开启基线初始化，Flyway无法识别已有数据库状态；解决方案：设置spring.flyway.baseline-on-migrate: true，自动创建版本历史表并标记基线版本。

易出错点3：生产环境误触发删除操作，导致数据丢失

现象：执行clean命令后，数据库所有表及数据被删除；原因：spring.flyway.clean-disabled未设为true，允许执行删除操作；解决方案：生产环境强制设置spring.flyway.clean-disabled: true，禁用clean命令，本地开发可谨慎设为false。

易出错点4：依赖缺失，启动报驱动或数据源相关错误

现象：项目启动报“Could not load driver class com.mysql.cj.jdbc.Driver”或“ No qualifying bean of type 'javax.sql.DataSource' available”；原因：缺少MySQL驱动、JDBC依赖，或未引入flyway-mysql依赖；解决方案：手动添加mysql-connector-j、spring-boot-starter-jdbc和flyway-mysql依赖，版本与Flyway核心依赖保持一致。

易出错点5：JDK版本过低，导致项目无法启动

现象：项目启动报“Unsupported major.minor version”，无法正常启动；原因：JDK版本低于17，不满足SpringBoot3的强制要求；解决方案：升级JDK至17（推荐17.0.8稳定版），并在pom.xml中指定JDK编译版本。

易出错点6：多数据源场景，仅主数据源脚本执行

现象：项目存在多数据源时，仅主数据源的Flyway脚本执行，其他数据源无变化；原因：Flyway默认仅绑定主数据源，不自动识别其他数据源；解决方案：关闭Flyway自动配置（spring.flyway.enabled: false），手动为每个数据源配置Flyway，脚本按数据源分目录存放。

五、实战总结

SpringBoot3集成Flyway的核心是“版本匹配+规范操作”，记住以下要点，即可顺利落地、规避大部分问题：

1. 版本适配：SpringBoot3.2.x+Flyway10.x+JDK≥17；

2. 依赖补齐：手动添加MySQL驱动、JDBC依赖和flyway-mysql依赖，版本与Flyway核心依赖保持一致；

3. 脚本规范：严格遵循命名格式，一个脚本做一件事；

4. 核心配置：非空库开baseline-on-migrate，生产环境开clean-disabled；

5. 排查技巧：遇到问题开启Flyway DEBUG日志。

若在集成过程中遇到其他问题，欢迎在评论区交流经验，共同规避错误、提升效率～