解决 Android Studio 编译错误：Unknown Kotlin JVM target: 21

问题描述

升级到 Android Studio Ladybug（2024.2）版本后，编译项目时出现「Unknown Kotlin JVM target: 21」错误。尽管项目配置中已明确设置 jvmTarget = "17"，迁移到 KSP 也未能解决问题。错误提示 Gradle/Kotlin 编译器无法识别 Java 21 目标，导致项目无法编译。

// 用户原有配置
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

kotlinOptions {
    jvmTarget = "17"
}

核心问题

错误并非源于配置错误，而是 Android Studio 更新后环境变更导致：

1. Gradle JDK 自动切换到 Java 21
2. Kotlin 插件版本与新环境不兼容
3. 配置未完整生效

解决方案概览

方案	操作位置	关键措施
环境重置	Android Studio 设置	修改 Gradle JDK 为 17
构建配置	build.gradle	添加 jvmToolchain 配置
插件升级	settings.gradle	更新 Kotlin 插件版本
深度清理	项目文件	清除缓存与临时文件

---

完整解决方案

方案一：重置 Gradle JDK（首选方案）

这是最常见的解决方案，适用于大多数情况：

操作步骤:

1. 打开 File > Settings > Build, Execution, Deployment > Build Tools > Gradle
2. 在「Gradle JDK」选项中选择:
   • jbr-17 (JetBrains Runtime 17)
   • 或 Amazon Corretto 17
3. 点击「Apply」保存设置

方案二：完善构建配置

在模块级 build.gradle.kts (或 build.gradle) 中添加 jvmToolchain 配置块：

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17"
    }
    
    // 添加此配置块
    kotlin {
        jvmToolchain(17) // 关键修复项
    }
}

方案三：更新 Kotlin 插件版本

在项目级 build.gradle 中明确指定 Kotlin 插件版本：

buildscript {
    dependencies {
        // 确保使用版本 2.0.x
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21"
    }
}

在 settings.gradle 中同步插件版本：

pluginManagement {
    plugins {
        id("org.jetbrains.kotlin.android") version "2.0.21"
        id("com.android.application") version "8.7.1"
    }
}

方案四：深度清理缓存

完成配置更改后执行彻底清理：

# 在项目根目录执行
rm -rf .gradle   # 删除 Gradle 缓存
rm -rf build     # 删除编译产物
./gradlew clean  # 执行 Gradle 清理任务

在 Android Studio 中：

1. 选择 File > Invalidate Caches / Restart...
2. 点击 Invalidate and Restart
3. 待 IDE 重启后同步项目

方案五：Gradle 版本升级

修改 gradle-wrapper.properties 文件：

# 升级到兼容版本
distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-all.zip

迁移到 KSP（可选）

若使用注解处理推荐迁移到 KSP：

// 替换 kapt 依赖
plugins {
    id("com.google.devtools.ksp") version "2.0.0-1.0.22"
}

dependencies {
    // 替换原有 kapt 配置
    ksp("com.example:processor:1.0.0") 
}

技术原理

问题本质是工具链不匹配：

1. Gradle JDK 变更：Android Studio 更新后默认 JDK 变为 21
2. 版本兼容性断层：Kotlin 旧版本插件无法识别 Java 21
3. 配置覆盖：kotlinOptions 未完整传递到所有编译任务

重要提示

• 避免混合版本（如使用 Java 21 + Kotlin 1.8）
• Kotlin 2.0+ 才能兼容 Java 21
• JDK 17 仍是当前（2025）Android 开发最稳定版本

延伸建议

1. 环境变量检查：

   # 终端执行检查
   echo $JAVA_HOME
   java -version

2. 多模块项目：确保所有模块的 compileOptions 和 kotlinOptions 一致
3. 插件兼容表：

Kotlin 版本	支持 JDK 版本
1.6-1.8	8-17
2.0+	17-21

遵循上述方案通常可立即解决问题。若仍遇到错误，请检查依赖库的编译目标设置，第三方库可能硬编码 JVM 目标导致冲突。