Compose Compiler 与 Kotlin 版本兼容性问题

问题描述

在 Android Studio 使用 Jetpack Compose 时，可能出现以下错误提示：

This version (1.3.2) of the Compose Compiler requires Kotlin version 1.7.20 but you appear to be using Kotlin version 1.8.0 which is not known to be compatible.
Please fix your configuration (or `suppressKotlinVersionCompatibilityCheck` but don't say I didn't warn you!)

该错误表明项目中配置的 Compose Compiler 版本与当前使用的 Kotlin 版本存在兼容性问题。根本原因是 Compose 编译器对 Kotlin 版本有严格依赖，若版本不匹配会导致构建失败。

解决方案

✅ 方案一：使用 Kotlin 2.0.0+ 及 Compose Gradle 插件（推荐）

对于 Kotlin 2.0.0 及以上版本，官方推荐使用 Compose Compiler Gradle 插件替代手动版本管理：

1. 在项目级 build.gradle.kts 中添加插件：

// 项目级 build.gradle.kts
plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "2.0.20" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.20" // 与 Kotlin 版本一致
}

2. 在模块级 build.gradle.kts 中启用插件：

// 模块级 build.gradle.kts (如 app 模块)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose") // 启用 Compose 插件
}

3. 移除旧版配置： 删除模块中过时的 composeOptions 配置块：

// ⚠️ 删除以下代码
android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2" 
    }
}

✅ 方案二：严格匹配版本组合

若使用 Kotlin 1.9.x~1.8.x，需手动确保版本兼容性。参考官方最新兼容表：

Compose Compiler 版本	兼容 Kotlin 版本
1.5.12	1.9.23
1.5.8	1.9.22
1.5.7	1.9.21
1.4.8	1.8.22
1.4.7	1.8.21
1.4.6	1.8.20
1.4.0	1.8.0
1.3.2	1.7.20

✨ 完整版本兼容列表参考

正确配置示例 (Groovy)：

// 项目级 build.gradle
plugins {
    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false // Kotlin版本
}

// 模块级 build.gradle
android {
    composeOptions {
        kotlinCompilerExtensionVersion '1.5.12' // 匹配 Kotlin 1.9.23
    }
}

⚠ 方案三：检查多平台项目配置

在 KMM 等多平台项目中，避免在非 Android 模块错误启用 Compose：

// ⚠ 错误示例：在公共模块启用 Compose
buildFeatures {
    compose = true 
}

仅应在 Android 应用模块中启用 Compose 支持。

⛔ 临时方案：抑制版本检查（不推荐）

kotlinOptions {
    freeCompilerArgs += [
        "-Xallow-jvm-ir-dependencies",
        "-P",
        "plugin:androidx.compose.compiler.plugins.kotlin:suppressKotlinVersionCompatibilityCheck=true" 
    ]
}

警告

此方法绕过兼容性检查，可能导致运行时崩溃或未定义行为，仅限临时调试使用。

最佳实践总结

1. 优先升级至 Kotlin 2.0.0+：使用官方 Compose 插件自动处理兼容性
2. 精确匹配版本：参考兼容表调整 kotlinCompilerExtensionVersion
3. 避免错误配置：不在非 Android 模块启用 Compose
4. 定期检查更新：关注 Jetpack Compose 发布日志

保持 Kotlin 和 Compose 版本同步更新可有效预防此类问题。当遇到兼容性错误时，先检查官方兼容性文档再调整配置。