Gradle Kotlin项目的apiVersion有什么作用-java教程-PHP中文网

apiVersion 控制 Kotlin 编译器对标准库 API 的可见性，决定编译时能调用哪些函数/属性；它与 languageVersion（控制语法特性）分离，需在 android { kotlinOptions { apiVersion = "1.8" } } 中显式配置，否则默认不生效，升级 Kotlin 版本后易因未同步该值导致 Unresolved reference 编译错误。

gradle kotlin项目的apiversion有什么作用

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 可提前暴露潜在的运行时兼容风险，而不是等到用户设备上崩溃。

Gradle 9.8.0

下载

实际配置示例与易忽略点

在 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 里。