在 kotlinOptions 中添加编译参数需置于 android {} 或 KotlinCompile 任务作用域内，用 freeCompilerArgs 数组传入 -X 开头的实验选项（如 "-Xjvm-default=all"），jvmTarget 等标准参数直接赋值，注意与 JDK、AGP 版本兼容。
怎么在 kotlinOptions 里加编译参数
Gradle Kotlin 项目添加额外编译参数，核心是往 kotlinOptions 块里写。它不是全局生效的开关，必须放在对应模块的 build.gradle（或 build.gradle.kts）中、android {} 或 tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile) 作用域内。
常见错误是直接写在 buildscript 或顶层 ext 里——那不会影响 Kotlin 编译器行为。
-
kotlinOptions必须和 Kotlin 插件版本兼容；例如 Kotlin 1.9+ 推荐用jvmTarget = "11"，而不是已废弃的target = "1.8" - 若项目含 Android 模块，优先在
android { kotlinOptions { ... } }中配置；纯 JVM 模块则用tasks.withType<kotlincompile> { kotlinOptions { ... } }</kotlincompile> - 参数名区分大小写：
-Xjvm-default=all是合法的实验性选项，但写成-xjvm-default会被忽略且无报错
-X 开头的实验性选项怎么启用
像 -Xjvm-default、-Xskip-prerelease-check 这类以 -X 开头的选项，属于 Kotlin 编译器的实验性功能，不能用普通键值对方式设置，必须通过 freeCompilerArgs 数组传入。
例如启用默认方法生成：
kotlinOptions {
jvmTarget = "11"
freeCompilerArgs += ["-Xjvm-default=all", "-Xskip-prerelease-check"]
}
- 多个参数要分开写进数组，不要合并成一个字符串（如
"-Xjvm-default=all -Xskip-prerelease-check"会失败） - 部分
-X选项有版本限制：比如-Xcontext-receivers在 Kotlin 1.6.20 才稳定，旧版启用会直接编译失败 - Android 项目中启用
-Xjvm-default后，Java 调用 Kotlin 接口默认方法时可能触发IncompatibleClassChangeError，需同步检查 Java 端调用方是否升级了 AGP 和 JDK
为什么 javaCompileOptions 不影响 Kotlin 编译
有人误把 Java 的编译参数配置（如 javaCompileOptions.forkOptions.jvmArgs）套用到 Kotlin 上，结果参数完全不生效——因为 javaCompileOptions 只控制 javac，而 Kotlin 是由独立的 KotlinCompile 任务执行的。
- Kotlin 编译器（kotlinc）不读取
javaCompileOptions，也不响应options.compilerArgs - 想给 Kotlin 编译器传 JVM 启动参数（比如加大内存），得改
org.gradle.jvmargs（在gradle.properties中），不是改编译任务本身 - 混淆相关参数（如 R8 的
-keep）属于打包阶段，跟kotlinOptions无关，别混在一起配
容易被忽略的兼容性陷阱
最常踩的坑不是参数写错，而是参数之间或参数与环境冲突。
-
jvmTarget = "17"和sourceCompatibility = JavaVersion.VERSION_11并存时，Kotlin 生成的字节码可能含 Java 17 特性（如 sealed class），但 Java 编译器仍按 11 处理，运行时报UnsupportedClassVersionError - 用了
-Xuse-ir（IR 后端）后，某些老版本 AGP（如 7.4.x）会无法识别生成的 stubs，导致 kapt 失败，报Cannot find symbol -
freeCompilerArgs += "-Xopt-in=kotlin.RequiresOptIn"启用 opt-in 后，所有调用方代码必须加@OptIn注解，否则编译失败——这个约束不会在 IDE 实时提示，只在 Gradle 构建时爆发
参数不是加得越多越好，尤其涉及 IR、默认方法、上下文接收者这类特性时，务必确认上下游工具链（AGP、JDK、IDE）版本是否真正支持。
