GitHub Actions中Liquibase校验和变更引发验证失败的排查求助

先搞懂报错原因 #

这个错误是因为Liquibase检测到你已经执行过的变更集changelog.sql::3::snowflake内容被修改了，或者本地与Runner环境的校验和生成逻辑存在差异，导致前后校验和不匹配。

GitHub Action及Runner里的调试步骤 #

1. 核对变更集内容是否一致 #

• 本地和Runner环境中的changelog.sql里，标记为3::snowflake的那段SQL必须完全一致，包括换行符、空格等细节。
• 在GitHub Action中添加步骤打印这段内容，方便对比：

  - name: 打印目标变更集内容
    run: cat path/to/changelog.sql | grep -A 20 -B 5 "::3::snowflake"
  

• 检查换行符差异：Liquibase对CRLF（Windows格式）和LF（Linux格式）换行符敏感，会直接影响校验和生成。在Runner中执行以下命令确认格式：

  file path/to/changelog.sql
  

  若存在差异，可在Git中配置换行符自动转换来统一格式。

2. 确认Liquibase版本完全匹配 #

不同版本的Liquibase校验和算法可能存在差异，必须保证本地与Action中使用的版本完全一致。

• 在Action中添加步骤打印当前Liquibase版本：

  - name: 检查Liquibase版本
    run: liquibase --version
  

  将结果与本地执行liquibase --version的输出对比，确保版本号完全相同。

3. 排查Runner环境的Liquibase配置 #

• 检查Action中的Liquibase命令是否指定了错误的变更日志路径，或者存在额外配置参数影响校验和计算。
• 可在Action中打印当前Liquibase的配置信息：

  liquibase --defaultsFile=liquibase.properties status
  

4. 临时跳过校验和验证（仅用于调试） #

如果想快速确认是否是校验和问题导致的失败，可在执行Liquibase命令时添加--validate=false参数跳过校验：

- name: 跳过校验执行Liquibase更新
  run: liquibase update --validate=false

注意：此方法仅用于调试，不可长期使用，否则会失去Liquibase对变更集完整性的校验能力。

5. 合法修改后更新校验和 #

如果你确实需要修改已执行过的变更集，先在本地执行以下命令更新数据库中存储的校验和：

liquibase clearCheckSums

提交变更后重新运行GitHub Action即可。

避坑提醒 #

• 尽量不要修改已执行过的变更集，推荐新增变更集来调整数据库结构。
• 保证GitHub Runner的操作系统、Java版本与本地开发环境一致，Java版本差异也可能导致校验和生成异常。

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