Spring Boot 集成 Liquibase 需引入官方 Starter（如 liquibase-core + spring-boot-starter-jdbc），确保未排除 LiquibaseAutoConfiguration；checksum mismatch 应优先用 clear-checksums 或 rollback 处理，禁用 MARK_RAN。
怎么在 Spring Boot 项目里加 Liquibase 依赖
直接加 liquibase-core 不够，Spring Boot 会自动配置 Liquibase，但前提是得让 Boot 认出它。最稳妥的方式是引入官方 Starter：org.liquibase:liquibase-core + org.springframework.boot:spring-boot-starter-jdbc（已含），再确认没排除 LiquibaseAutoConfiguration。
常见错误现象：Caused by: java.lang.ClassNotFoundException: liquibase.integration.spring.SpringLiquibase —— 这说明只加了老版本的 liquibase-core，没加 Spring 集成桥接类；或者用了新版 Liquibase（4.20+）但 Spring Boot 版本太低（
- Spring Boot 2.7–3.1：用 Liquibase 4.17–4.28，
spring.liquibase.enabled=true默认开启 - Spring Boot 3.2+：底层换用
LiquibaseDataSource，需确保spring.liquibase.*配置项仍被识别（部分配置项已弃用，如spring.liquibase.change-log改为spring.liquibase.change-log-path） - 别手动 new
SpringLiquibase注入容器 —— 会绕过 Boot 自动配置，导致事务、数据源绑定异常
change-log 文件路径和格式怎么写才不报错
spring.liquibase.change-log 指向的文件必须存在、可读、且是 Liquibase 能解析的格式（changelog.xml / changelog.yaml / changelog.json）。默认路径是 classpath:/db/changelog/db.changelog-master.yaml，但很多人直接写 db.changelog.yml 结果找不到。
常见错误现象：Cannot find changelog location: class path resource [db/changelog/db.changelog-master.yaml] —— 实际文件叫 master.yaml 却配成了 master.xml；或文件放在 src/main/resources 下但路径写成 file:./db/changelog/...（Liquibase 默认只查 classpath）。
立即学习“Java免费学习笔记（深入）”；
- 推荐统一用
yaml格式，语义清晰、支持注释、不易因缩进崩掉 - 根 changelog 必须声明
databaseChangeLog:（注意末尾冒号），子文件用include:引入，路径是相对于该文件的位置 - 不要在
change-log中写绝对路径或环境变量占位符（如${user.home}）—— Liquibase 解析时还没走 Spring 的 PropertySource
如何让每次启动都执行 migration 且不卡住应用
Liquibase 默认在 ApplicationContext 刷新早期就执行变更，如果数据库连不上、SQL 有语法错误、或锁表时间长，整个 Spring Boot 启动就会 hang 住甚至失败。这不是 bug，是设计行为 —— 它要确保“应用看到的数据库结构永远和代码一致”。
常见错误现象：本地启动慢、CI 环境构建失败、测试容器反复重启。根本原因常是 spring.liquibase.enabled=true 在所有 profile 都生效，包括 test 和 ci。
- 开发阶段建议设
spring.liquibase.enabled=${LIQUIBASE_ENABLED:true}，通过环境变量控制开关 - 测试用 H2 时，加上
spring.liquibase.drop-first=true（仅限 test profile），避免历史 checksum 冲突 - 生产环境务必关掉
spring.liquibase.liquibase-schema（默认 public），改用专用 schema 如liquibase，防止误删业务表 - 如果迁移耗时 >30s，考虑拆分大 changelog：用
includeAll加目录，配合logicalFilePath控制顺序
checksum mismatch 错误到底该怎么修
这是 Liquibase 最让人抓狂的问题：Validation Failed: 1 change sets check sum。本质是 Liquibase 把每个 changeSet 的内容（含空格、换行、注释）做了哈希，存进 databasechangelog 表。一旦你改了已执行过的 SQL，哈希值对不上，就报错。
别急着删 databasechangelog 表 —— 生产库这么干等于删库。真正安全的做法取决于你改的是什么。
- 只是改了注释或空格？用
liquibase clear-checksums命令重算（需 CLI 或 JUnit 测试中调用） - 改了 SQL 逻辑但还没上线？回退代码，用
rollback撤销，再提交新 changeSet（推荐） - 已上线又必须改？加
validCheckSum: ANY到对应 changeSet，但仅限紧急修复，下次迁移前得补上正式 rollback - 永远别用
preConditions里写onFail: MARK_RAN来跳过校验 —— 这会让 Liquibase 认为“这个变更已经成功执行”，后续无法追溯真实状态
最麻烦的其实是团队协作场景：A 提交了 changeSet，B 拉代码后本地执行失败，因为 B 的数据库里已有 A 的旧版记录，但 checksum 已变。这时候不是谁对谁错，而是没约定好“变更提交即不可修改”的协作纪律。
