Gradle版本与JDK必须严格匹配，如Gradle 8.0+需JDK 17+，不匹配会导致Unsupported class file major version等错误；应使用gradle wrapper、SDKMAN管理版本，并在build.gradle.kts中显式配置JVM toolchain。
Gradle版本与JDK必须匹配
Gradle不是“装上就能用”，它对JDK有硬性要求。比如 Gradle 8.0+ 要求最低 JDK 17，而 Gradle 7.6 最高只支持到 JDK 20。用错组合会导致 Unsupported class file major version 或构建直接失败。
- 查当前Gradle版本支持的JDK范围：看官网
https://docs.gradle.org/current/userguide/compatibility.html - 检查本地JDK：
java -version和javac -version必须一致，且是完整JDK（不是JRE） - 推荐方式：用SDKMAN管理多版本JDK，再通过
gradle wrapper绑定项目级Gradle版本，避免全局污染
用gradle wrapper而不是全局gradle命令
团队协作或CI环境里，gradle 命令调用的是系统PATH里的全局Gradle，极易和项目实际需要的版本不一致。所有Java项目都应使用 ./gradlew（Linux/macOS）或 gradlew.bat（Windows）。
- 初始化wrapper：
gradle wrapper --gradle-version 8.5（指定版本） - 生成后会创建
gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.jar和gradle-wrapper.properties -
gradle-wrapper.properties中的distributionUrl必须是HTTPS地址，否则IDE可能拉取失败 - 提交整个
gradle/目录到Git，但忽略.gradle/（用户级缓存）和build/（构建产物）
IDEA中正确识别Gradle项目的关键配置
IntelliJ IDEA导入时默认走“Auto-import”，但常因网络、代理或缓存导致依赖解析失败、源码不附带、test源码未标记等问题。
- 关闭“Use default gradle wrapper” → 改为“Use gradle ‘wrapper’ task configuration”
- 勾选“Import gradle project automatically”和“Keep source folders structure”
- 若依赖没下载完，不要点“Reload project”，先检查
~/.gradle/daemon/下是否有卡住的Daemon进程，可手动杀掉再重试 - 如果
src/test/java没被识别为Test Sources，右键目录 → “Mark as Test Sources Root”，这是常见但容易忽略的手动补救点
build.gradle.kts里必须声明JVM目标版本
即使JDK版本正确，不显式配置编译目标，Kotlin/Java代码仍可能生成不兼容的字节码。尤其在混合Java/Kotlin项目中，java { } 块和 kotlin { } 块必须各自明确 toolchain。
立即学习“Java免费学习笔记（深入）”；
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
kotlin {
jvmToolchain(17)
}
- 不写这个，
javac可能用JDK 17编译但输出class文件版本为61（对应Java 17），而运行环境若只有JDK 11就会报java.lang.UnsupportedClassVersionError - Gradle 8+ 默认启用
--release编译参数，但仅当toolchain明确时才生效；否则它会退回到宿主JDK的默认行为 - 若项目需兼容老JRE，不能只改
sourceCompatibility，必须用toolchain+--release组合保证符号引用安全
gradle-wrapper.properties 里URL被公司代理拦截却没报错，只安静地卡在“Resolving dependencies”。这些点不排查到位，重装十次IDE都没用。 
