第4章 Kotlin编译器版本不匹配

4.1 现象识别

构建项目时出现以下错误，编译中断：

Unsupported Kotlin version. The Kotlin compiler extension version (1.5.21) 
does not match the required Kotlin compiler version (1.9.0). 
Please update kotlinCompilerExtensionVersion in your build.gradle.

该错误通常出现在使用Compose Compiler的Kotlin编译器扩展（kotlinCompilerExtensionVersion）与项目实际使用的Kotlin编译器版本（kotlinVersion）不兼容时。错误提示中会直接指出当前扩展版本与期望的Kotlin版本，是定位问题的第一线索。

4.2 数据采集

收集以下三个关键数据，形成排查表：

4.3 原因定位

核心原因：kotlinCompilerExtensionVersion 与 Kotlin 版本之间存在严格的对应关系。Compose Compiler 的每个版本只支持特定范围的 Kotlin 版本。下表列出常用对应规则：

判断规则：若 kotlinCompilerExtensionVersion 不在项目使用的 Kotlin 版本所支持的范围内，则触发错误。例如：项目使用 Kotlin 1.9.0，但 kotlinCompilerExtensionVersion 为 1.6.0（需要 Kotlin 2.0.0），则出现不匹配。

4.4 故障树分析

下图为 Kotlin 版本不匹配问题的故障树，展示从现象到根因的排查路径：

4.5 修复动作

1. 确定目标兼容对：根据项目使用的 Kotlin 版本，从兼容矩阵中找到对应的 kotlinCompilerExtensionVersion。若 Kotlin 是 1.9.22，则扩展版本应选 1.5.4 – 1.5.8 区间内的一个。
2. 更新 build.gradle.kts：

// 在 android 块中
composeOptions {
    kotlinCompilerExtensionVersion = "1.5.8"
}
// 或者在 libs.versions.toml 中更新版本号后同步

3. 或者升级 Kotlin 版本：如果项目需要较新扩展特性，可对应增加 Kotlin 版本。

// 在 root 或模块 build.gradle.kts 中
kotlin("jvm") version "1.9.23"
// 同步后，扩展版本可保留为 1.5.8 或升级至 1.5.10+

4.6 复测及预防

复测步骤：

• 执行 ./gradlew assembleDebug（Android）或对应构建命令，观察是否不再出现 Unsupported Kotlin version 错误。
• 检查编译日志中是否有其他不兼容警告（如Kotlin API版本弃用）。
• 运行单元测试验证Compose代码正常编译。

预防措施：