Kotlin 2.0 项目解决要求 Compose Compiler Gradle 插件的问题

问题描述

在 Android 项目中使用 Kotlin 版本 2.0.20 时（尽管用户声明了 ext.kotlin_version = '1.9.0'，但实际使用的是 2.0.20 插件），编译会出现以下错误提示：

Starting in Kotlin 2.0, the Compose Compiler Gradle plugin is required when compose is enabled. See the following link for more information: https://d.android.com/r/studio-ui/compose-compiler

根本原因是：Kotlin 2.0+ 版本中，Compose 编译器不再内置在 Kotlin 核心，必须单独声明和配置插件。即使设置了 composeOptions 的旧参数（如 kotlinCompilerExtensionVersion），若不添加新的编译器插件，仍会触发此错误。

解决方案

根据 Android 官方文档和社区实践，以下是两种主流配置方案：

方案一：使用版本目录管理（推荐，适合新项目）

1. 在 libs.versions.toml 中定义版本和插件：

[versions]
kotlin = "2.0.20" # 确保此处与项目实际Kotlin版本一致

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

2. 在根目录 build.gradle 中声明插件：

plugins {
    // ...其他声明
    alias(libs.plugins.compose.compiler) apply false
}

3. 在 App 模块的 build.gradle 中应用插件：

plugins {
    // ...其他插件
    alias(libs.plugins.compose.compiler)
}

方案二：传统 Gradle 配置（适合未使用版本目录的项目）

1. 根目录 build.gradle 添加类路径：

buildscript {
    dependencies {
        classpath "org.jetbrains.kotlin.plugin.compose:org.jetbrains.kotlin.plugin.compose.gradle.plugin:$kotlin_version"
    }
}

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

apply plugin: "org.jetbrains.kotlin.plugin.compose"

3. 移除旧版依赖（如存在）：
   替换原 androidx.compose.compiler:compiler 依赖为：

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-compose-compiler-plugin-embeddable:$kotlin_version"
}

注意事项

1. 版本一致性： Kotlin 主插件 org.jetbrains.kotlin.android 的版本必须与 Compose 编译器 org.jetbrains.kotlin.plugin.compose 的版本严格同步

2. 更新 composeOptions：
   在模块级 build.gradle 中同步更新：

composeOptions {
    kotlinCompilerExtensionVersion = "2.0.0" // 需≥2.0.0
}

3. 避免配置冲突：

   • 不要同时声明 androidx.compose.compiler 和 kotlin-compose-compiler-plugin-embeddable
   • 确保项目中所有模块的 Kotlin 插件版本相同

4. 升级兼容性： 若从 Kotlin 1.9 升级到 2.0+，请一并更新所有 Jetpack Compose 相关库到兼容版本（如 androidx.compose.*:1.7.0+）

调试建议

在 Gradle 配置完成后执行：

./gradlew clean build --refresh-dependencies

可强制刷新依赖并清除历史缓存文件

错误案例分析

原问题中的关键错误点：

classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.20"
buildFeatures { compose = true }

虽然设置了 kotlinCompilerExtensionVersion "1.5.14"，但在 Kotlin 2.0+ 环境下缺失必要的编译器插件注册，导致构建失败。

参考文档

• Android 官方 Compose 编译器指南
• Kotlin Compose 编译器迁移说明