apiVersion 控制 Kotlin 编译器对标准库 API 的可见性，决定编译时能调用哪些函数/属性；它与 languageVersion（控制语法特性）分离，需在 android { kotlinOptions { apiVersion = "1.8" } } 中显式配置，否则默认不生效，升级 Kotlin 版本后易因未同步该值导致 Unresolved reference 编译错误。
apiVersion 控制 Kotlin 编译器对标准库 API 的可见性
apiVersion 是 Kotlin 编译器的一个编译选项，它不控制语言特性（那是 languageVersion 干的事），而是决定编译时能「看到」哪些 Kotlin 标准库的 API。比如你用 Kotlin 1.9 编译器，但设 apiVersion = "1.8"，那 listOfNotNull 这类 1.9 新增的函数就无法调用，编译器会报 Unresolved reference。
常见错误：升级 Kotlin 版本后突然编译失败
项目从 Kotlin 1.8 升到 1.9，但没改 apiVersion，结果部分代码调用了 takeIf 的新重载或 String.lines() 等新增 API，直接报错。这不是 IDE 缓存问题，是编译器主动屏蔽了这些符号。
- Gradle Kotlin DSL 中设置位置在
kotlinOptions块内，不是compileOptions - Android 项目中，若使用 AGP 8.3+，
kotlinOptions需写在模块级build.gradle.kts的android {}块里，而非顶层 - 值必须是合法的 Kotlin 版本字符串，如
"1.8"、"1.9"，不能写成"1.9.0"或"1.9.10"
和 languageVersion 的关键区别
languageVersion 决定你能写什么语法（比如 val (a, b) = pair 解构是否允许），apiVersion 只管你能用哪些函数/属性。两者可以不同：设 languageVersion = "1.9" + apiVersion = "1.8"，你就能用 1.9 的语法写代码，但只能调 Kotlin 1.8 标准库的 API —— 这在维护老 SDK 兼容性时很实用。
Android 项目中尤其要注意：如果 minSdk 较低（如 21），又依赖某些高版本 Kotlin 库的内部行为，收紧 apiVersion 可提前暴露潜在的运行时兼容风险，而不是等到用户设备上崩溃。
实际配置示例与易忽略点
在 build.gradle.kts 中正确写法是：
android {
kotlinOptions {
jvmTarget = "1.8"
apiVersion = "1.8" // ← 这行必须显式写，不会继承自 Kotlin 插件版本
languageVersion = "1.8"
}
}
容易踩的坑：
- 误以为升级了
org.jetbrains.kotlin:kotlin-gradle-plugin版本，apiVersion就自动更新 —— 它默认不生效，必须手动指定 - 在根
build.gradle.kts里配kotlinOptions，但 Android 模块实际读的是模块级配置，导致设置被忽略 - CI 环境未同步该字段，本地能编译，流水线失败
真正起作用的是编译期检查，它不改变字节码目标，也不影响运行时行为 —— 所以别指望靠它“降级”已编译的 class 文件。它的价值在于把 API 兼容性问题卡在编译阶段，而不是藏在 release 后的 crash log 里。
