第1章 Compose Compiler与Kotlin版本对应关系总览

Compose Compiler 作为 Jetpack Compose 的核心编译器插件，其版本与 Kotlin 编译器版本存在严格的绑定关系。错误的版本组合将导致构建失败或运行时异常。本章从官方映射表、版本号规律、兼容性矩阵三个维度建立完整的知识框架，为后续章节的适配操作提供理论基础。

1.1 官方映射表

Google 官方通过 compose-compiler 发布页和 androidx.compose 版本说明维护一张持续更新的映射表。下表列出了近几年主要版本的对应关系（截至 Compose BOM 2024.12）：

1.2 版本号规律

Compose Compiler 的版本号遵循 KotlinMajor.KotlinMinor.Patch 的模式：

• 主版本号：与 Kotlin 主版本号一致（例如 Kotlin 1.9 → Compose Compiler 1.5）。
• 次版本号：从 0 开始递增，每轮适配周期内可能更新 2~3 个次版本。
• 补丁版本：修复 Bug 或支持 Kotlin 小版本兼容，例如 1.5.10 → 1.5.11。

当 Kotlin 发布新主版本时，Compose Compiler 会跳过一个次版本号（如 1.5 → 1.6）以避免混淆。

// 在项目级 build.gradle.kts 中声明 Kotlin 版本
kotlin("jvm") version "2.0.20"
// Compose Compiler 版本必须对应 Kotlin 2.0.x → 1.5.20+
composeCompiler {
    compilerVersion.set("1.5.24")
}

1.3 兼容性矩阵

官方不保证跨版本兼容，以下矩阵总结已验证的可行组合与不可行组合：

1.4 验证与调试

在项目根目录执行以下 Gradle 任务，可快速检测当前配置的版本兼容性：

./gradlew :app:dependencies --configuration compileClasspath | grep -E "(compose-compiler|kotlin-stdlib)"

如果输出中 compose-compiler 的版本与 kotlin-stdlib 的版本不匹配，则构建日志会显示类似：

ERROR: Unsupported Kotlin version. Found 2.0.20, expected 1.9.22.
Compose Compiler requires Kotlin 2.0.x but you are using 1.9.x.

1.5 实战：Gradle 配置片段

在 build.gradle.kts（模块级）中声明版本依赖的推荐写法：

android {
    kotlinOptions {
        jvmTarget = "17"
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.24"
    }
}
kotlin {
    version = "2.0.20"
}

如果使用版本目录（libs.versions.toml），则统一管理版本：

[versions]
kotlin = "2.0.20"
compose-compiler = "1.5.24"

[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }

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

当版本冲突时，优先参考 Android Developers 官方兼容表，避免自行猜测。