--release参数必须与JDK工具链严格对齐，否则会报错或运行时失败；正确做法是用options.release（Gradle 6.7+）或javaToolchain（Gradle 17+），而非手动写compilerArgs；debugImplementation等不影响--release语义。
Gradle Java项目中设置 --release 参数，不是“加个参数就行”，而是必须和 JDK 工具链、编译目标语义严格对齐——否则会报 无效的标识: --release 或编译通过但运行时 NoClassDefFoundError。
为什么直接在 compilerArgs 里加 --release 常常失败
常见错误现象是：本地 IDE 能编译，CI 上失败；或 Gradle 构建成功，但运行时报错说找不到 java.lang.Record（明明用了 Java 14+）。根本原因在于：--release 是 javac 的“跨版本编译开关”，它要求底层 JDK 必须 ≥ 指定版本，且不依赖环境变量 JAVA_HOME 所指 JDK 的语言特性能力。如果你用 JDK 17 编译却写 --release 21，javac 直接拒绝——它只认自己支持的 --release 范围（JDK 17 支持 --release 8 到 --release 17）。
所以不能只写参数，得先确认工具链是否就位：
- 检查当前 Gradle 使用的 JDK 版本：
./gradlew -version输出里的JVM行 - 确认该 JDK 是否支持你要的
--release值（例如 JDK 19 支持--release 19，但不支持--release 20） - 避免混用：不要一边设
sourceCompatibility = JavaVersion.VERSION_19，一边又在compilerArgs里加--release 17——语义冲突
compileJava.options.compilerArgs 的正确写法
这是最直接的设置方式，但仅适用于明确需要跨版本兼容（比如生成能在 JRE 11 上跑的字节码，而你本地用的是 JDK 17）的场景。示例（Java 19 项目）：
compileJava {
options.release = "19"
// ✅ 推荐写法：用 options.release，而非手动 addAll(['--release', '19'])
// ❌ 避免手写 compilerArgs.addAll(['--release', '19']) —— 容易漏掉空格、引号、顺序问题
}
注意：options.release 是 Gradle 6.7+ 提供的类型安全封装，它自动处理参数拼接、校验，并与 sourceCompatibility 同步（设了 options.release = "19" 后，sourceCompatibility 就不该再单独设）。
如果非要用 compilerArgs（比如要同时加 --enable-preview），必须保证顺序和格式：
-
--release必须在--enable-preview之前（javac 解析顺序敏感） - 必须成对出现：
['--release', '19']，不能写成['--release 19']（单字符串会被当做一个参数） - 不能和
-source/-target共存——--release已隐含二者
更现代、更可靠的替代方案：Java Toolchain
Gradle 17+ 推荐用 javaToolchain 统一管理 JDK 版本，它比 --release 更彻底地解耦“编译用 JDK”和“源码/字节码目标版本”。配置后，--release 会自动推导，无需手动干预：
java {
toolchain {
languageVersion = JavaLanguageVersion.of(19)
}
}
这样 Gradle 会自动查找本地已安装的 JDK 19（或下载），并用它执行编译；同时默认启用等效的 --release 19 逻辑。好处是：
- CI 环境不再依赖
JAVA_HOME配置，Gradle 自动下载匹配 JDK - 多模块项目可为不同模块指定不同
languageVersion - 避免手写参数导致的拼写、顺序、引号错误
但要注意：Toolchain 不等于“忽略 --release”。当你启用预览特性（如 Java 19 的 VirtualThread）时，仍需显式加 options.enablePreview = true，因为 Toolchain 只管 JDK 版本，不管预览开关。
debugImplementation / releaseImplementation 会影响 --release 吗
完全不影响。debugImplementation 和 releaseImplementation 控制的是依赖的**编译期可见性与打包范围**，和字节码生成规则无关。它们决定某个库（比如 stetho）是否只参与 Debug 构建、是否打进最终 APK/JAR，但不改变 javac 如何解析语法或生成 class 文件。所以别指望靠换 dependency scope 来绕过 --release 限制——该报错还是报错，该不兼容还是不兼容。
真正容易被忽略的点是：如果你在 releaseImplementation 引入了一个只支持 Java 17+ API 的库，但主模块用了 --release 11，编译不会报错（因为依赖不参与语法检查），但运行时一调用那个 API 就崩。这种隐性不兼容，比编译报错更难排查。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
