Java 21 编译错误：Unsupported class file major version 65

问题描述

当开发者在 Gradle 项目中升级到 Java 21 时，可能会遇到以下编译错误：

startup failed:
General error during conversion: Unsupported class file major version 65

java.lang.IllegalArgumentException: Unsupported class file major version 65
at groovyjarjarasm.asm.ClassReader.<init>(ClassReader.java:199)
...

该问题通常发生在以下场景：

1. 在 gradle.properties 中设置了 Java 21 路径：

   org.gradle.java.home=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

2. 引入新的第三方依赖库后触发错误
3. 切换回 Java 17 可成功编译
4. 异常现象：使用 Java 17 成功编译后切换回 Java 21 也能编译通过

此错误表明 Gradle 使用的字节码处理工具无法识别 Java 21 的新类文件格式（major version 65），多数情况是由于环境配置不当导致的兼容性问题。

核心原因

错误本质是 Gradle 环境或项目配置未完全适配 Java 21：

1. Gradle JVM 版本不匹配：执行 Gradle 的 JVM 与项目目标版本不一致
2. 兼容性设置缺失：sourceCompatibility/targetCompatibility 未正确配置
3. 构建缓存冲突：遗留的编译缓存包含不兼容的字节码
4. 组件版本过旧：
   • Gradle 自身版本过低
   • Android Gradle 插件（AGP）等未更新
   • 依赖库不支持 Java 21

注意

Java 版本与类文件版本号对应关系：

• Java 17 → major version 61
• Java 21 → major version 65 Gradle 7.x 及以下无法识别 version 65

解决方案

1. 配置构建兼容性（必需）

在项目的 build.gradle 中明确设置兼容性目标：

// KTS 格式
java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

// 或传统格式
sourceCompatibility = 21
targetCompatibility = 21

2. 启用 Java Toolchain（推荐）

在 build.gradle 中使用 Toolchain 自动管理 JVM 版本，避免环境变量冲突：

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

3. 更新 Gradle 和组件

Gradle Wrapper

修改 gradle-wrapper.properties：

# 使用支持 Java 21 的版本 (≥8.4)
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

Android 项目

更新 settings.gradle 中的 AGP 版本：

plugins {
    id "com.android.application" version "8.5.0" apply false
    id "com.android.library" version "8.5.0" apply false
}

AGP 版本要求

Android Studio Iguana (2023.2)+ AGP ≥ 8.3.0 才官方支持 Java 21

4. 检查环境变量

# 检查系统 JAVA_HOME
echo $JAVA_HOME

# 理想路径应指向 JDK 21
/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home

确保：

1. 无冲突的旧版本 JDK 存在路径中
2. IDE（Intellij/VSCode）中的 Gradle JVM 设置与项目一致

5. 清理缓存

执行以下命令清理 Gradle 缓存：

# 清理构建缓存
./gradlew clean

# 彻底删除 .gradle 缓存 (谨慎操作)
rm -rf ~/.gradle/caches

配置验证清单

完成修复后，请确认以下配置全部正确：

配置位置	要求	示例值
gradle.properties	org.gradle.java.home	JDK 21 安装路径
build.gradle	sourceCompatibility	21 / VERSION_21
build.gradle	使用 Java Toolchain	languageVersion=21
gradle-wrapper.properties	distributionUrl	gradle-8.7-bin.zip
环境变量	JAVA_HOME	指向 JDK 21

总结

出现 Unsupported class file major version 65 的本质是 Gradle 运行时环境或项目配置未能完全适配 Java 21。遵循以下原则可彻底解决：

1. 强制指定兼容性：在 build.gradle 中显式设置 source/target compatibility
2. 使用 Toolchain：让 Gradle 自动管理 JVM 版本依赖
3. 升级关键组件：使用 Gradle ≥8.4 和相应插件新版
4. 环境一致性：确保命令行与 IDE 使用相同的 JDK 21 环境
5. 清理历史缓存：删除 .gradle 目录解决缓存冲突

遵循上述步骤后，项目应能稳定编译，成功利用 Java 21 的新特性。