Gradle引入本地编译的Flyway Gradle插件失败，求助排查

问题背景 #

我克隆了Flyway源码的指定分支，编译生成了flyway-gradle-plugin-0-SNAPSHOT.jar和flyway-core-0-SNAPSHOT.jar，将它们复制到目标项目的libs目录后，在build.gradle.kts中配置如下：

buildscript {
    repositories {
        flatDir {
            dirs("libs")
        }
    }
    dependencies {
        classpath("com.google.protobuf:protobuf-gradle-plugin:0.8.19")
        classpath(":flyway-gradle-plugin:0-SNAPSHOT")
        classpath(":flyway-core:0-SNAPSHOT")
    }
}

apply {
    plugin("org.flywaydb.flyway-gradle-plugin")
    // plugin(":flyway-gradle-plugin")
    // plugin("org.flywaydb.gradle.FlywayPlugin") 
}

运行时出现报错：

FAILURE: Build failed with an exception.

* Where:
Build file '/n/Projects/user-stats/build.gradle.kts' line: 27

* What went wrong:
Plugin with id 'org.flywaydb.flyway-gradle-plugin' not found.

同时尝试了plugins块的多种写法，均无法解决：

plugins {
    //id("org.flywaydb.flyway") version ("0-SNAPSHOT")
    //id("org.flywaydb.flyway")
    //id("org.flywaydb.flyway-gradle-plugin") version ("0-SNAPSHOT")
    //id("flyway-gradle-plugin") version ("0-SNAPSHOT")
    //id("flyway-gradle-plugin")
    //id("org.flywaydb.gradle.FlywayPlugin")
}

问题原因及解决办法 #

1. 插件ID错误 #

Flyway官方Gradle插件的标准ID是org.flywaydb.flyway，而非你尝试的org.flywaydb.flyway-gradle-plugin或其他变种。你可以通过以下方式确认插件ID：

• 解压flyway-gradle-plugin-0-SNAPSHOT.jar，查看META-INF/gradle-plugins目录下的.properties文件名，该文件名就是插件的合法ID（比如org.flywaydb.flyway.properties对应ID为org.flywaydb.flyway）。

2. FlatDir依赖声明的可靠性问题 #

使用flatDir仓库时，依赖声明可能因为匹配规则导致无法正确找到jar包，建议直接通过文件路径声明classpath，避免匹配问题：

buildscript {
    dependencies {
        classpath("com.google.protobuf:protobuf-gradle-plugin:0.8.19")
        classpath(files("libs/flyway-gradle-plugin-0-SNAPSHOT.jar"))
        classpath(files("libs/flyway-core-0-SNAPSHOT.jar"))
    }
}

3. 正确应用插件 #

确认插件ID后，修改apply语句：

apply(plugin = "org.flywaydb.flyway")

或者直接通过插件类的全限定名应用（需确保classpath中包含该类）：

apply(plugin = org.flywaydb.gradle.FlywayPlugin::class)

4. Plugins块无法直接使用本地快照 #

plugins块默认从Gradle Plugin Portal拉取插件，本地快照版本无法通过plugins块的id声明直接引用，必须配合buildscript + apply的方式，或者在项目根目录的settings.gradle.kts中配置pluginManagement引入flatDir仓库：

pluginManagement {
    repositories {
        flatDir {
            dirs("libs")
        }
        gradlePluginPortal()
    }
}

之后才能在plugins块中使用本地快照版本：

plugins {
    id("org.flywaydb.flyway") version "0-SNAPSHOT"
}

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