Gradle 项目中的版本声明方式：kotlinVersion、composeCompilerVersion 与 ext 变量管理

在 Kotlin + Compose 多模块项目中，Kotlin 版本与 Compose Compiler 版本必须严格对齐。版本声明方式决定了版本的一致性、可维护性以及升级成本。本章剖析 Gradle 项目中最常用的三种声明方式：kotlinVersion、composeCompilerVersion 以及 ext 变量管理，并给出标准化实现流程与常见错误避坑指南。

2.1 原理：为什么需要在 Gradle 中集中声明版本

每个模块如果各自硬编码 Kotlin 与 Compose Compiler 版本，升级时需逐一修改，极易出现版本不匹配。集中声明通过以下机制解决：

• 单点维护：在根项目的 ext 块或 buildScript 块中定义一次。
• 全局引用：子模块通过 rootProject.ext.kotlinVersion 或直接引用变量访问。
• 编译插件注入：composeCompilerVersion 直接影响 Compose Compiler Gradle 插件的选择，与 kotlinVersion 一一对应。

2.2 实现流程：标准版版本声明

以下流程适用于 Kotlin DSL（.kts）和 Groovy DSL（.gradle）项目。推荐使用 Kotlin DSL 以获得类型安全。

1. 在根项目 build.gradle.kts 中声明 ext 变量：定义 kotlinVersion 和 composeCompilerVersion。
2. 在 buildScript 块中引用：将变量注入到插件版本中。
3. 子模块通过 rootProject.ext 读取：确保所有模块使用统一版本。
4. 验证：通过 Gradle 任务打印版本，或在编译日志中确认。

2.2.1 根项目配置示例（Kotlin DSL）

// build.gradle.kts (项目级)
plugins {
    kotlin("jvm") version embeddedKotlinVersion apply false
    id("org.jetbrains.compose") version "1.6.0" apply false
}

ext {
    // 集中声明版本
    set("kotlinVersion", "1.9.22")
    set("composeCompilerVersion", "1.5.11")
}

subprojects {
    // 子模块统一应用 Kotlin 插件
    apply(plugin = "kotlin")
    apply(plugin = "org.jetbrains.compose")

    // 引用 ext 变量
    kotlin {
        jvmToolchain(17)
    }
    compose {
        kotlinCompilerPluginVersion.set(rootProject.ext.get("composeCompilerVersion") as String)
    }
}

2.2.2 使用 Groovy DSL 的等效写法

// build.gradle (项目级)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.9.22' apply false
    id 'org.jetbrains.compose' version '1.6.0' apply false
}

ext {
    kotlinVersion = '1.9.22'
    composeCompilerVersion = '1.5.11'
}

subprojects {
    apply plugin: 'org.jetbrains.kotlin.jvm'
    apply plugin: 'org.jetbrains.compose'

    kotlin {
        jvmToolchain(17)
    }
    compose {
        kotlinCompilerPluginVersion = rootProject.ext.composeCompilerVersion
    }
}

2.3 调试：验证版本是否生效

在任意子模块中添加 Gradle 任务打印当前使用的版本：

// 子模块 build.gradle.kts 中添加
tasks.register("printVersions") {
    doLast {
        println("Kotlin version: ${rootProject.ext.get("kotlinVersion")}")
        println("Compose Compiler version: ${rootProject.ext.get("composeCompilerVersion")}")
        println("Actual Kotlin plugin version: ${embeddedKotlinVersion}")
    }
}

运行 ./gradlew :app:printVersions 输出示例：

Kotlin version: 1.9.22
Compose Compiler version: 1.5.11
Actual Kotlin plugin version: 1.9.22

2.4 常见错误与性能优化

性能优化建议：

• 避免在 subprojects 块中频繁调用 rootProject.ext.get()，可在根项目预定义局部变量后传递给子模块。
• 使用 Gradle 配置缓存（configuration cache）时，确保 ext 变量在配置阶段常量化，避免动态计算。

2.5 版本声明关系图

下图展示版本变量在 Gradle 项目中的定义、传递与最终使用关系：

2.6 小结

• 使用 ext 变量统一声明 kotlinVersion 和 composeCompilerVersion 是 Gradle 多模块项目的标准实践。
• 版本集中管理将升级成本从 O(n) 降低到 O(1)，同时避免编译器版本不匹配导致的构建失败。
• 调试时通过自定义任务打印版本可快速定位问题；关注 ext 作用域和类型转换细节。