第2章 Gradle 中 Compose Compiler 插件声明方式：kotlinCompilerExtensionVersion、kotlinCompilerPlugin、版本变量管理

2.1 原理：从扩展属性到专用插件

Compose Compiler 是 Kotlin 编译器插件之一，它将 @Composable 函数、状态管理等语法转换为底层字节码。Gradle 中声明该插件的版本经历了两个阶段：

• 传统方式：kotlinCompilerExtensionVersion —— 在 AGP 的 composeOptions 块内通过扩展属性指定，隐式随 Kotlin 编译器一同加载。
• 现代方式：kotlinCompilerPlugin —— 自 Kotlin 2.0 起，Compose Compiler 作为独立 Gradle 插件发布，需显式 apply 或放在 plugins 块中。

两种方式的核心差异在于：传统方式与 Kotlin 版本绑定（每个 Kotlin 版本对应唯一的 Compose Compiler 版本），现代方式解耦，允许各自独立升级。无论哪种方式，版本变量管理都是避免构建环境混乱的关键。

2.2 实现流程：两种声明方式详解

2.2.1 传统方式（kotlinCompilerExtensionVersion）

// 模块 build.gradle.kts
android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }
}

注意事项：

• 该版本必须与 Kotlin 编译器版本兼容，否则编译失败或产生运行时异常。
• 无法在同一项目中对不同模块使用不同的 Compose Compiler 版本（全局生效）。

2.2.2 现代方式（kotlinCompilerPlugin）

// 根 build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.1.0"
}

// 子模块无需再设置 composeOptions，但需启用 Compose（AGP 8.0+ 默认开启）

若通过 apply 方式（Kotlin 2.0+ 多模块场景）：

// 子模块 build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.plugin.compose")
}

优势：插件版本与 Kotlin 版本分离，方便紧急修复或功能预览。

2.3 版本变量管理：集中化与一致性

无论使用哪种声明方式，强烈建议将 Compose Compiler 版本号提取到 Gradle 版本目录（Version Catalog）或 项目级 ext / buildscript 变量中，避免硬编码。

2.3.1 使用 libs.versions.toml（推荐）

在 gradle/libs.versions.toml 中定义：

[versions]
kotlin = "2.1.0"
compose-compiler = "2.1.0"  // 现代插件方式

[libraries]
// 如果你用传统方式，可以只存版本字符串

[plugins]
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "compose-compiler" }

然后在模块中引用：

// 根 build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.compose)
}

2.3.2 使用 ext 全局变量（传统方式）

// 根 build.gradle.kts
ext {
    set("composeCompilerVersion", "1.5.10")
}

// 模块 build.gradle.kts
android {
    composeOptions {
        kotlinCompilerExtensionVersion = rootProject.ext["composeCompilerVersion"] as String
    }
}

2.4 调试与验证

如何确认当前项目实际使用的 Compose Compiler 版本？

• 传统方式：执行 ./gradlew :app:dependencies --configuration compileClasspath，搜索 androidx.compose.compiler 或 compose-compiler。
• 现代插件方式：查看 ./gradlew buildEnvironment，搜索 kotlin-compose-compiler-plugin。
• 运行时日志：启用 KotlinCompile 任务的 info 日志 ./gradlew :app:compileDebugKotlin --info | grep -i compose，可看到编译器参数包含 -P plugin:org.jetbrains.kotlin.compose: 等。

2.5 常见错误与解决方案

2.6 性能与稳定性优化

• 缓存友好：使用 kotlinCompilerPlugin 方式时，Gradle 构建缓存和配置缓存可正常工作；传统方式下若版本变化频繁，缓存命中率可能下降。
• 统一版本变量：在 libs.versions.toml 中声明，并通过 Renovate 定期检查更新，避免手动升级遗漏。
• K2 编译器配合：从 Kotlin 2.0 起，推荐使用 kotlinCompilerPlugin 并启用新的 K2 编译器模式，Compose 编译性能提升约 2 倍。

2.7 流程图：Compose Compiler 版本声明路径选择

下图展示了从传统方式到现代插件的演进以及版本变量管理的推荐流程：

2.8 本章小结

• 明确两种声明方式的适用场景与版本映射规则。
• 掌握在 build.gradle.kts 中的具体配置语法。
• 版本变量管理是维护多模块、多人团队项目的基石，务必替代硬编码。
• 利用 Gradle 日志和依赖报告快速定位版本不兼容问题。