Liquibase Java API配置searchPath问题求助（v4.13+）

问题背景 #

在Liquibase v4早期版本中，以下代码可以正常运行：

Liquibase liquibase = new liquibase.Liquibase("path/to/changelog.xml", new ClassLoaderResourceAccessor(), database);

liquibase.update(new Contexts(), new LabelExpression());

但升级到v4.17.0或v4.19.0版本后，出现报错：

The file path/to/changelog.xml was not found in the configured search path:
More locations can be added with the 'searchPath' parameter.

尝试以下配置后仍无法解决问题，需要正确的searchPath配置方式：

Map<String, Object> config = new HashMap<>();
config.put("liquibase.searchPath", "/");

Scope.child(config, () -> {

  Liquibase liquibase = new liquibase.Liquibase("path/to/changelog.xml", new ClassLoaderResourceAccessor(), database);

  liquibase.update(new Contexts(), new LabelExpression());
});

正确配置方案 #

根据你的changelog文件位置，选择以下任意一种配置方式：

1. 针对类路径资源的配置 #

如果你的path/to/changelog.xml位于类路径根目录下，将searchPath设为空字符串即可：

Map<String, Object> config = new HashMap<>();
config.put("liquibase.searchPath", "");

Scope.child(config, () -> {
  Liquibase liquibase = new liquibase.Liquibase("path/to/changelog.xml", new ClassLoaderResourceAccessor(), database);
  liquibase.update(new Contexts(), new LabelExpression());
});

空字符串代表类路径的根目录，Liquibase会从这里开始查找指定的changelog文件。

2. 针对文件系统绝对路径的配置 #

如果changelog文件在本地文件系统中（而非类路径），需要指定文件系统的绝对根路径，同时替换为FileSystemResourceAccessor：

Map<String, Object> config = new HashMap<>();
// 替换为你实际的文件根目录绝对路径
config.put("liquibase.searchPath", "/Users/yourname/project/src/main/resources");

Scope.child(config, () -> {
  Liquibase liquibase = new liquibase.Liquibase("path/to/changelog.xml", new FileSystemResourceAccessor(), database);
  liquibase.update(new Contexts(), new LabelExpression());
});

3. 不配置searchPath，直接指定ResourceAccessor的根路径 #

也可以跳过searchPath配置，直接给ClassLoaderResourceAccessor传入根路径参数：

ClassLoaderResourceAccessor resourceAccessor = new ClassLoaderResourceAccessor(
    Thread.currentThread().getContextClassLoader(),
    Collections.singletonList("") // 指定类路径根为查找起点
);

Liquibase liquibase = new liquibase.Liquibase("path/to/changelog.xml", resourceAccessor, database);
liquibase.update(new Contexts(), new LabelExpression());

关键注意事项 #

• liquibase.searchPath的取值是相对于ResourceAccessor的根路径，不是操作系统的绝对路径
• 使用ClassLoaderResourceAccessor时，searchPath为空字符串代表类路径根，不要用"/"（这会被解析为类路径下的/目录，通常不存在）
• 如果changelog文件和当前类在同一包下，可以将searchPath设为当前包的相对路径，比如"com/yourcompany/db"

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