Spring集成Liquibase报BeanCreationException及changelog解析异常求解

核心报错信息：
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'liquibase' defined in class path resource [org/springframework/boot/autoconfigure/liquibase/LiquibaseAutoConfiguration$LiquibaseConfiguration.class]: Invocation of init method failed; nested exception is liquibase.exception.ChangeLogParseException: Error parsing classpath:/db/changelog/db.changelog-master.yml

以下按问题出现概率从高到低排序排查：

1. YAML语法格式错误（占该类问题80%以上） #

• 缩进校验：Liquibase对YAML缩进敏感度极高，必须统一使用2个空格缩进，禁止使用Tab字符，同层级节点缩进必须完全对齐，最常见错误为databaseChangeLog根节点下的changeSet缩进偏移1个空格
• 特殊字符转义：若changeSet内的SQL、备注文本包含冒号:、井号#、单/双引号等YAML特殊字符，必须用单引号包裹整段属性值，例如comment: '初始化用户表: 新增核心字段'，未转义的冒号会被YAML解析器识别为键值对分隔符直接触发解析失败
• 必填字段校验：每个changeSet节点必须同时配置id、author两个必填属性，缺失任意一个都会抛解析异常
• 快速定位方法：可通过如下单测直接加载changelog文件，SnakeYAML（Spring、Liquibase默认使用的YAML解析器）会直接抛出具体错误行号，无需反复启动应用排查

  import org.yaml.snakeyaml.Yaml;
  import java.io.InputStream;
  public class YamlSyntaxCheck {
      public static void main(String[] args) {
          InputStream is = YamlSyntaxCheck.class.getClassLoader().getResourceAsStream("db/changelog/db.changelog-master.yml");
          new Yaml().load(is); // 该行抛出的异常会明确标注语法错误位置
          System.out.println("YAML语法校验通过");
      }
  }
  

2. 依赖与版本适配问题 #

• YAML解析依赖缺失：Spring Boot 2.4+版本中，解析YAML格式changelog依赖SnakeYAML组件，常规Web场景默认会引入该依赖，若使用自定义精简Starter、或手动排除过相关依赖，需手动补全依赖：

  <dependency>
      <groupId>org.yaml</groupId>
      <artifactId>snakeyaml</artifactId>
  </dependency>
  

• Liquibase版本不匹配：不要手动指定与当前Spring Boot版本不兼容的Liquibase版本，例如Spring Boot 2.7.x默认适配Liquibase 4.9.x，Spring Boot 3.2.x默认适配Liquibase 4.24.x，版本错位会导致YAML解析逻辑不兼容触发报错

3. 文件路径与编码问题 #

• 路径一致性校验：确认spring.liquibase.change-log配置的路径与文件实际存放路径完全一致，注意classpath路径下文件夹、文件名大小写敏感——Windows环境不区分大小写会掩盖路径错误，部署到Linux环境时会直接触发文件解析失败
• 文件编码校验：changelog文件必须保存为UTF-8无BOM格式，若用Windows记事本等工具编辑后保存为UTF-8带BOM格式，文件开头的BOM头会被解析器识别为非法字符直接报错，可通过IDEA右下角编码选项直接转换格式

4. changelog内容兼容性问题 #

• 标签版本适配：若使用了高版本Liquibase才支持的标签/属性，而实际运行的Liquibase版本较低，会触发解析失败，例如includeAll标签的errorIfMissingOrEmpty属性为Liquibase 4.15版本新增，低版本无法识别；此类问题要么升级Liquibase到适配版本，要么删除不兼容的属性配置
• 子changelog校验：如果主changelog通过include、includeAll标签引入了其他子changelog文件，任意子文件存在语法、格式错误，都会统一抛出主changelog解析失败的异常，需对所有引入的子文件逐一做语法校验

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