📚 课程目录第3章解析Gradle构建脚本中的版本声明

解析 Gradle 构建脚本中的版本声明

在 Jetpack Compose 的 Gradle 构建脚本中，kotlinVersion、composeCompilerVersion 与 kotlinCompilerExtensionVersion 这三个声明共同决定了项目的语言特性、编译器版本及最终产物的兼容性。误配或漏配任意一项，都可能导致编译失败或运行时异常。本章将拆解这三个声明的语法位置、职责边界与配对逻辑。

核心原则： Compose 编译器是 Kotlin 编译器的“前端插件”，其版本必须与 Kotlin 编译器本体严格锁定。项目中的版本声明链条为：

Kotlin 语言版本 → Kotlin 编译器版本 → Compose 编译器插件版本。

三个声明的职责边界

虽然这三个变量都出现在 Gradle 脚本中，但它们作用于编译过程的不同阶段，且生命周期完全不同。错误的赋值会导致“鸡同鸭讲”式的编译错误。

声明变量	作用对象	影响范围	常见声明位置
kotlinVersion	Kotlin 语言 / 标准库	JVM 目标版本、语言特性、API 集合	`buildscript` 或 `plugins` 块
composeCompilerVersion	Compose 编译器插件	Compose 代码生成、@Composable 转换	`plugins` / `composeCompiler` 块
kotlinCompilerExtensionVersion	Compose 编译器扩展 (旧)	与 `composeCompilerVersion` 相同，但语法不同	`composeOptions` 块 (已废弃倾向)

Gradle 声明语法演进

理解历史版本有助于你阅读旧项目。现代项目（Kotlin 2.0+）已趋向于统一语法。

方式一：传统 composeOptions（Compose 编译器 1.x）

在 Kotlin < 2.0 时，Compose 编译器版本通过 composeOptions 块声明。kotlinCompilerExtensionVersion 是这个块中的关键字段。

// build.gradle.kts (Module: app)
android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }
}

方式二：现代 composeCompiler 块（Compose 编译器 2.x+）

从 Kotlin 2.0 开始，Compose 编译器作为一个独立的 Kotlin 编译器插件发布。你需要在 plugins 块中应用 kotlin("plugin.compose")，然后在 composeCompiler 块中指定版本。

// build.gradle.kts (Module: app)
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.21"
}

composeCompiler {
    kotlinCompilerExtensionVersion = "1.5.15"
}

版本对应速查：

Kotlin 版本 → Compose Compiler Extension 版本
1.9.22    → 1.5.10
1.9.23    → 1.5.11
1.9.24    → 1.5.14
2.0.0     → 1.5.14
2.0.21    → 1.5.15

版本锁与编译异常

当 kotlinVersion 与 kotlinCompilerExtensionVersion 不匹配时，编译器会抛出类似以下异常：

Cannot inline bytecode built with JVM target 1.8 into bytecode that is being built with JVM target 17

/ 或 /

'composable' invocations cannot be resolved

这些异常的根源在于 Compose 编译器插件版本对应的元数据格式与 Kotlin 编译器版本不一致。Gradle 构建脚本中的版本声明不仅仅是数字，而是精确的互锁齿轮。

推荐的多模块统一管理策略

为了防止版本扩散，应在项目级 build.gradle.kts 或 libs.versions.toml 版本目录中集中声明。

项目级 build.gradle.kts:

// 定义版本常量
val kotlinVersion by extra("2.0.21")
val composeCompilerVersion by extra("1.5.15")

// 应用 Kotlin 插件版本
plugins {
    kotlin("jvm") version kotlinVersion apply false
    kotlin("plugin.compose") version kotlinVersion apply false
}

模块级 build.gradle.kts:

plugins {
    kotlin("plugin.compose")
}

composeCompiler {
    kotlinCompilerExtensionVersion = rootProject.extra["composeCompilerVersion"] as String
}

常见陷阱：

拼写错误： kotlinCompilerExtensionVersion 极易与 kotlinCompilerVersion 混淆，后者已废弃且含义不同。
版本目录覆盖： 如果在 libs.versions.toml 中定义了版本，又在模块中硬编码，Gradle 会优先使用模块级声明，导致不一致。
Hilt 或 KSP 冲突： 其他注解处理器（如 Hilt、KSP）也可能依赖 Kotlin 编译器版本，升级时需同步检查。

调试步骤：验证版本是否锁定

检查插件依赖树：

./gradlew :app:dependencies --configuration compileClasspath

确认 Kotlin 编译器版本：
```
./gradlew :app:tasks --group kotlin
```
验证 Compose 编译器版本： 在编译日志中搜索 ComposeCompiler 或 KotlinCompilerExtension 字样。
对比官方兼容表： 访问 Android Developers 官网的 Compose 编译器兼容性映射表，确保三个数值（Kotlin 版本、AGP 版本、Compose 编译器版本）落在推荐的组合内。

正确声明这三个版本是 Compose 项目健康运行的第一步。下一构建环节中，Gradle 将根据你声明的版本锁，拉取对应的编译器插件并执行合成。在之后的章节中，我们将深入探讨当版本锁被打破时，如何通过编译器错误信息定位根因。