解决Liquibase 4.0报错：请使用相对路径或为classpath参数添加'/'

问题复现 #

触发报错信息：

Specifying files by absolute path was removed in Liquibase 4.0. Please use a relative path or add '/' to the classpath parameter.

场景说明：

• 未单独安装Liquibase，通过Maven/Eclipse运行对接PostgreSQL的Spring项目，所有运行渠道均触发上述报错
• 使用Liquibase版本为4.9.1，目标引用changelog文件路径为db/changelog/db.changelog-master.xml
• 初始pom.xml中liquibase-maven-plugin配置如下（存在错误）：

<plugin>
   <groupId>org.liquibase</groupId>
   <artifactId>liquibase-maven-plugin</artifactId>
   <configuration>
       <propertyFile>/src/main/resources/liquibase.properties</propertyFile>
       <changeLogFile>/db/changelog/db.changelog-master.xml</changeLogFile>
   </configuration>
</plugin>

• 已尝试的错误方案：
  • 在liquibase.properties中配置classpath为classpath:/db/changelog/db.changelog-master.xml后，Eclipse启动抛出BeanCreationException嵌套异常，提示找不到db/changelog-base.xml，重复触发原路径报错
  • 将Maven插件中changeLogFile配置修改为/src/main/resources/db/changelog/db.changelog-master.xml后，执行mvn liquibase:update可正常运行，但Eclipse中以Java Application方式启动配置了spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml的Spring Boot项目仍启动失败

根因说明 #

报错核心是Liquibase 4.0及以上版本移除了绝对路径指定文件的支持，所有以/开头的路径都会被识别为非法绝对路径抛出异常；同时Maven插件执行、Spring Boot启动、IDE运行时的classpath加载逻辑存在差异，混用文件系统绝对路径、classpath路径会出现单场景可用、其他场景报错的问题。另外changelog内部嵌套引用其他拆分changelog文件时，如果路径带开头/，也会重复触发该报错。

正确配置步骤 #

1. 修正pom.xml中liquibase-maven-plugin配置 #

去掉所有路径开头的/，不写文件系统绝对路径，统一使用相对路径，显式指定classpath和插件版本，保证和项目引入的Liquibase版本对齐：

<plugin>
   <groupId>org.liquibase</groupId>
   <artifactId>liquibase-maven-plugin</artifactId>
   <version>4.9.1</version>
   <configuration>
       <!-- propertyFile相对于pom.xml所在目录写相对路径，去掉开头/ -->
       <propertyFile>src/main/resources/liquibase.properties</propertyFile>
       <!-- changeLogFile写相对于classpath根的路径，去掉开头/ -->
       <changeLogFile>db/changelog/db.changelog-master.xml</changeLogFile>
       <!-- 显式将资源目录加入classpath，避免路径解析失败 -->
       <classpath>
           <classpathEntry>src/main/resources</classpathEntry>
       </classpath>
   </configuration>
   <dependencies>
       <!-- 引入PostgreSQL驱动，保证Maven执行插件时可正常连接数据库 -->
       <dependency>
           <groupId>org.postgresql</groupId>
           <artifactId>postgresql</artifactId>
           <scope>runtime</scope>
       </dependency>
   </dependencies>
</plugin>

2. 修正Spring Boot启动配置 #

不管使用properties还是yml格式配置，路径不要带开头斜杠：

• application.properties写法：

spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml

• application.yml写法：

spring:
  liquibase:
    change-log: classpath:db/changelog/db.changelog-master.xml

3. 修正liquibase.properties配置 #

配置文件内所有路径去掉开头/，不要额外加classpath:前缀：

# 数据库连接信息按实际环境替换
url=jdbc:postgresql://localhost:5432/你的数据库名
username=你的数据库用户名
password=你的数据库密码
driver=org.postgresql.Driver
# changelog路径直接写classpath下的相对路径
changeLogFile=db/changelog/db.changelog-master.xml

4. 检查changelog内部嵌套引用 #

主changelog中include其他拆分的changelog文件（比如db.changelog-base.xml）时，路径同样不能带开头/，正确写法示例：

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
    http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">
    <!-- 错误写法：<include file="/db/changelog/db.changelog-base.xml"/> -->
    <include file="db/changelog/db.changelog-base.xml"/>
</databaseChangeLog>

验证方式 #

1. 执行mvn clean liquibase:update，确认Maven侧执行无路径报错，可正常执行changelog
2. 执行mvn clean compile重新编译资源文件，清理IDE旧缓存
3. 在Eclipse中以Java Application方式启动Spring Boot项目，确认Liquibase正常加载changelog，项目启动无异常

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