基于Kotlin开发并发布Gradle插件的构建配置咨询

一、先搞定版本对齐——解决Embedded Kotlin冲突的核心 #

你遇到的版本冲突问题，根源就是手动设置的Kotlin版本和Gradle内置的Embedded Kotlin版本不匹配。绝对不要硬写Kotlin版本号，直接用Gradle提供的embeddedKotlinVersion变量，它会自动和当前Gradle版本绑定（比如Gradle 8.0.2对应的Kotlin版本是1.8.20）。

在构建脚本开头的plugins块里这么写：

plugins {
    `java-gradle-plugin`
    kotlin("jvm") version embeddedKotlinVersion
    `maven-publish`
    `plugin-publish` // 发布到Gradle Plugin Portal的必备插件
}

二、基础项目配置 #

1. JVM版本适配 #

Gradle 8.x要求插件运行在Java 11及以上，配置目标JVM版本：

java {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

kotlin {
    jvmToolchain(11)
}

2. 插件元数据配置 #

用java-gradle-plugin自动生成插件元数据，不用手动编写json：

gradlePlugin {
    plugins {
        create("myKotlinPlugin") {
            id = "com.example.my-kotlin-plugin" // 插件唯一ID，遵循反向域名规则
            implementationClass = "com.example.MyKotlinPlugin" // 插件主类全路径
            displayName = "My Kotlin Gradle Plugin"
            description = "用Kotlin开发的示例Gradle插件"
        }
    }
}

三、彻底避免Kotlin依赖冲突 #

别自己加固定版本的kotlin-stdlib依赖！直接用Gradle提供的声明，它们会自动对齐Embedded Kotlin版本：

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation(kotlin("reflect"))
    implementation(gradleApi()) // 开发插件必须引入的Gradle API
    // 测试依赖
    testImplementation(kotlin("test"))
    testImplementation(gradleTestKit()) // 测试Gradle插件的专用工具包
}

四、发布到Gradle Plugin Portal的配置 #

1. 补充发布元数据 #

用plugin-publish配置插件的检索信息，方便用户找到你的插件：

pluginBundle {
    website = "https://example.com/my-plugin" // 可选，填插件官网地址
    vcsUrl = "https://github.com/example/my-kotlin-plugin" // 必填，代码仓库地址
    tags = listOf("kotlin", "gradle", "plugin") // 检索标签
}

2. 配置认证信息 #

在本地~/.gradle/gradle.properties文件中添加Gradle Plugin Portal的密钥（需先在Portal注册账号并获取API密钥）：

gradle.publish.key=你的发布密钥
gradle.publish.secret=你的发布密码

五、测试配置 #

用JUnit Platform运行插件测试：

tasks.test {
    useJUnitPlatform()
}

完整的build.gradle.kts示例 #

plugins {
    `java-gradle-plugin`
    kotlin("jvm") version embeddedKotlinVersion
    `maven-publish`
    `plugin-publish`
}

group = "com.example"
version = "1.0.0"

java {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

kotlin {
    jvmToolchain(11)
}

gradlePlugin {
    plugins {
        create("myKotlinPlugin") {
            id = "com.example.my-kotlin-plugin"
            implementationClass = "com.example.MyKotlinPlugin"
            displayName = "My Kotlin Gradle Plugin"
            description = "用Kotlin开发的示例Gradle插件"
        }
    }
}

pluginBundle {
    website = "https://example.com/my-plugin"
    vcsUrl = "https://github.com/example/my-kotlin-plugin"
    tags = listOf("kotlin", "gradle", "plugin")
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation(kotlin("reflect"))
    implementation(gradleApi())
    testImplementation(kotlin("test"))
    testImplementation(gradleTestKit())
}

tasks.test {
    useJUnitPlatform()
}

关键提醒 #

• 永远用embeddedKotlinVersion指定Kotlin插件版本，这是解决版本冲突的唯一可靠方式。
• 绝对不要手动引入独立版本的Kotlin标准库，依赖kotlin("stdlib-jdk8")即可。
• 发布前先执行./gradlew publishPlugins --dry-run检查配置，避免发布出错。

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