1. Compose Compiler 与 Kotlin 版本的对应关系表：官方映射、版本号编码规则、常见组合

1.1 原理：为什么 Compiler 必须与 Kotlin 版本绑定？

Jetpack Compose 使用 Kotlin 编译器插件在编译阶段将 @Composable 函数、remember、mutableStateOf 等声明式语法转换为底层 Android 字节码。这个转换过程高度依赖 Kotlin 编译器内部 AST（抽象语法树）和 IR（中间表示）的稳定 API。Kotlin 每个大版本（1.5 → 1.6 → 1.7 → 1.8）的 IR 结构、编译器内部类路径和方法签名均可能改变。

Compose Compiler 针对特定 Kotlin 版本编译，版本号采用语义化版本 + Kotlin 版本标识的编码规则。若 Compiler 版本与项目实际 Kotlin 版本不匹配，轻则编译期报错“Unsupported Kotlin version”，重则造成运行时布局异常或 @Composable 函数无法正确内联。

1.2 版本号编码规则：解析 Compose Compiler artifact

Compose Compiler 的 Maven 坐标格式为：

androidx.compose.compiler:compiler-compiler:版本号

版本号采用 主版本.次版本.修订号-rcxx（预发布）或 主版本.次版本.修订号（稳定版）。在 1.5.0 之后，Compose Compiler 版本号中直接嵌入其所依赖的 Kotlin 版本信息：

编码规则演变：

• 早期（1.4.x 及之前）： Compiler 版本与 Kotlin 版本无显式关联，需查阅官方兼容性表格。
• 中期（1.5.x ~ 1.7.x）： 采用 1.x.0 格式，每升一个 Compiler 次版本号即对应一个新的 Kotlin 主版本。
• 当前（1.8.0+）： Compiler 版本号中的修订号（第三段）用于标记针对同一 Kotlin 版本的补丁或优化，例如 1.8.0 和 1.8.10 都绑定 Kotlin 1.9.22，但后者修复了部分 K2 模式下的兼容问题。

1.3 官方映射表（稳定版）

下表列出主流 Crates 中经过 Android Studio 与官方 AGP 验证的推荐组合：

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.22"
}

android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.8.0"
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

// ❌ 错误：Kotlin 1.9.22 与 Compiler 1.7.0 不兼容
kotlinCompilerExtensionVersion = "1.7.0"  // 期望 1.8.0

1.4 常见错误与调试方法

错误模式 1：版本不匹配编译崩溃

日志摘录：

e: This version (1.8.0) of the Compose Compiler requires Kotlin version 1.9.22 but you appear to be using Kotlin version 1.9.0 which is not compatible.
e: To workaround this, please use the Kotlin version from the table in the docs at https://developer.android.com/jetpack/androidx/releases/compose-kotlin

解决方案：

1. 确认 Gradle 构建日志中的 Kotlin 版本：
   ./gradlew -v | grep Kotlin 或查看 .gradle/8.x/kotlin 目录下的版本信息。
2. 同步修改 plugins 块中的 kotlin 版本与 composeOptions.kotlinCompilerExtensionVersion 为官方映射表中对应的组合。

错误模式 2：运行时布局异常（无编译错误）

当 Compiler 版本与 Kotlin 版本属于“弱兼容”组合（例如某些 rc 版或预发布版），常出现 @Composable 函数重组异常或 State 无法感知更新。此类错误通常在发布包中更隐蔽，需开启 composeCompilerMetrics 和 composeCompilerReports 进行诊断：

// build.gradle.kts
android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.8.0"
    }
    buildFeatures {
        compose = true
    }
    kotlinOptions {
        freeCompilerArgs += listOf(
            "-P",
            "plugin:androidx.compose.compiler.plugins.kotlin:composeCompilerMetrics=" +
            "${project.buildDir}/compose-metrics"
        )
        freeCompilerArgs += listOf(
            "-P",
            "plugin:androidx.compose.compiler.plugins.kotlin:composeCompilerReports=" +
            "${project.buildDir}/compose-reports"
        )
    }
}

编译后在 build/compose-metrics 下生成 JSON 报告，检查 composableFunctionCount 和 restartableFunctionCount 是否符合预期。

1.5 稳定性与性能优化建议

• 锁定注解版本： 使用 libs.version.toml 版本目录管理 Compose Compiler 版本，避免临时升级 Kotlin 导致连锁升级。
• 增量编译优化： 在 Kotlin 2.0 + Compose 2.0 组合中，开启 K2 模式可使 @Composable 函数增量编译速度提升约 40%。
• 主版本升级策略： 建议每 6 个月跟随 Compose Compiler 稳定版升级一次，借助 compose-compiler-gradle-plugin 的 composeCompilerBlocks 功能逐步适配。

1.6 版本对应关系流程图

下图展示 Compose Compiler 与 Kotlin 版本之间的严格映射、兼容性验证流程以及升级路径：

1.7 常见组合速查表（含非稳定版）

对于需要尝鲜最新 Kotlin 特性的团队，以下组合为经过社区验证的有效搭配（非官方稳定版，建议加锁版本）：

1.8 调试关键命令

命令行直接查询项目当前 Kotlin 及 Compiler 版本（基于 Gradle 8.x）：

# 查看已解析的 kotlin 版本
./gradlew kotlinVersion

# 查看 compose compiler 版本
./gradlew -q dependencies --configuration implementation | grep compose-compiler

若版本不一致，优先检查 gradle.properties 中是否覆盖了 kotlin.version：

# 避免在 gradle.properties 中硬编码 kotlin 版本
# kotlin.version=1.9.22 ❌ 应由 build.gradle.kts 的 plugins 块统一管理