必须添加spring-boot-starter-flyway依赖（Spring Boot项目），而非仅flyway-core；需配置flyway.locations、flyway.schemas、flyway.validate-on-migrate等关键参数；SQL脚本须严格遵循V版本__描述.sql命名规范，注意换行符与数据库兼容性。
怎么在Maven项目里加Flyway依赖
Java项目用Flyway，第一步不是写SQL，而是让项目“认识”它。Spring Boot 2.4+ 默认内置了 FlywayAutoConfiguration，但前提是依赖得对——否则启动直接报 ClassNotFoundException 或者迁移不触发。
关键点：别只加 flyway-core，Spring Boot 用户必须配 spring-boot-starter-flyway（它会自动拉取兼容版本的 flyway-core 和适配器）；纯 Maven + Spring（非Boot）才需要手动配 flyway-core + 对应数据库驱动适配器（如 flyway-mysql）。
-
spring-boot-starter-flyway是首选，版本跟 Spring Boot 主版本强绑定（比如 Boot 3.2.x 对应 Flyway 9.2.x，Boot 2.7.x 对应 Flyway 8.5.x） - 如果手动指定
flyway-core版本，务必检查其 官方支持矩阵，MySQL 8.0.33+ 需要 Flyway ≥ 8.5.13，否则CREATE TABLE ... ENCRYPTION='Y'语句会解析失败 - 依赖冲突常见于项目里已有旧版
flyway-core（比如 5.x），和spring-boot-starter-flyway拉的 9.x 冲突，启动时抛NoClassDefFoundError: org/flywaydb/core/api/configuration/FluentConfiguration
application.yml 里哪些配置不能少
Flyway 默认只认 src/main/resources/db/migration 下的 SQL 文件，且要求命名格式为 V1__init.sql。但实际项目中路径、前缀、校验行为都得显式控制，否则上线后发现没执行、或执行了两次、或校验失败停服。
最常漏配的是 flyway.enabled 和 flyway.validate-on-migrate —— 前者默认 true（没问题），后者默认 true（危险）：只要历史脚本 checksum 变了（比如你改了已发布的 V2 脚本），应用就起不来。
立即学习“Java免费学习笔记（深入）”；
-
flyway.locations: classpath:db/migration—— 必须显式声明，尤其多模块项目，避免因 classpath 扫描顺序导致脚本漏加载 -
flyway.schemas: my_app_db—— 显式指定 schema，防止 Flyway 在 public schema 下建flyway_schema_history表（PostgreSQL 尤其容易踩这个坑） -
flyway.validate-on-migrate: false—— 开发/测试环境可关，生产环境建议保留 true，但要确保所有脚本只增不改 -
flyway.baseline-on-migrate: true—— 已有旧库接入 Flyway 时救命用，但必须配合flyway.baseline-version=1.0，否则 baseline 默认是 1，而你的第一个脚本是 V1__xxx，会冲突
SQL 脚本命名和内容怎么写才不翻车
Flyway 不是简单按文件名排序执行，它靠 V + 版本号 + __ + 描述 + 后缀识别顺序。写错一个下划线、多一个空格、版本号跳着写，轻则执行乱序，重则启动失败。
常见错误现象：V1__create_user.sql 执行了，V2__add_email_index.sql 却没执行，日志里只有一句 Skip failed migration —— 其实是 V2 文件名里用了中文破折号“－”而不是英文减号“-”，被解析成非法版本号。
- 版本号必须是数字，支持点分（
V1.2.3）、支持单数字（V1），但V1.01和V1.1会被视为不同版本（前者 > 后者），慎用带前导零的写法 - 描述部分不能含空格开头/结尾，不能含
#、/* */等注释符号在第一行（某些版本会把注释当描述解析，导致 checksum 计算异常） - MySQL 下避免在脚本里写
USE my_db;—— Flyway 迁移时连接的是配置的 database，USE 会切换上下文，导致后续 DDL 在错误库执行 - PostgreSQL 下，如果脚本里有
COMMIT，必须配flyway.group: true，否则每条语句自动 commit，事务断裂
怎么查 Flyway 到底干了啥
启动日志一闪而过，不知道它连了哪个库、执行了哪些脚本、为什么跳过某条——这是最让人抓狂的阶段。别猜，直接看 flyway_schema_history 表和日志开关。
Flyway 默认 INFO 级别只打关键步骤（如 “Successfully validated”、“Current version…”），想看到每条 SQL 执行耗时、连接 URL、甚至 JDBC PreparedStatement 绑定参数？得调日志级别。
- 加 JVM 参数
-Dlogging.level.org.flywaydb=DEBUG，能看到脚本加载路径、checksum 计算过程、SQL 执行前后时间戳 - 连上数据库查
SELECT * FROM flyway_schema_history ORDER BY installed_rank;—— 这张表是唯一真相：status 字段是Success还是Missing Success，installed_by 是谁，installed_on 时间戳是否合理 - 如果脚本执行失败，Flyway 默认 rollback 整个事务（H2/PostgreSQL 支持，MySQL 需要引擎是 InnoDB 且关闭 autocommit），但不会删已插入的
flyway_schema_history记录，所以改完脚本后要手动删掉那条失败记录再重启 - 别信 IDE 控制台最后一行 “Started Application in X seconds”，要看
org.flywaydb.core.internal.command.DbMigrate是否打出 “Successfully applied X migrations”
复杂点在于 Flyway 的校验逻辑嵌在 checksum 计算和历史表比对里，而 checksum 依赖文件内容（包括换行符）、数据库方言、甚至 Flyway 版本。同一份 SQL，在 Mac 上开发生成的 checksum，放到 Linux 服务器可能不一致——因为行尾符从 LF 变成了 CRLF（Git autocrlf 设置不当）。这事没法靠文档记住，只能靠查表 + DEBUG 日志交叉验证。
