全部配置 / APP-APIVERSION

API 版本

apiVersion · APP-APIVERSION · Gradle DSL · 同源入口 api-version

重要：高 · 影响大 默认：视情况（按目标/构建类型） 场合：场景可配 来源：上游原样

默认值：视情况。未设则跟工具链 API 默认走。使用场合：场景可配。场景可配：有明确目标（性能、包体、安全、兼容）时再改。

它是做什么的

用途。限制只能使用指定版本及更早的 Kotlin 标准库 API。用于兼容性约束；常见与 languageVersion 配合。

影响。锁定语言/API 能力边界；设错会导致源码无法编译或误用新 API。

适用场景。编译器/后端排查或信息查询；定位完成后关闭冗余输出。

取值说明

字符串

  • Default value: null

可写。<属性值> （Gradle Property：org.gradle.api.provider.Property<org.jetbrains.kotlin.gradle.dsl.KotlinVersion>）

定义依据：dsl/KotlinCommonCompilerOptions.kt 在仓库中打开

怎么用

  1. 配置入口：build.gradle.kts → kotlin.compilerOptions.apiVersion
  2. 示例：
// 文件：build.gradle.kts（应用的 Kotlin 模块，例如 composeApp）
kotlin {
  compilerOptions {
    apiVersion.set(/* value */)
  }
}
  1. 生效：Sync 后执行对应 Kotlin 编译任务。
  2. 验证：确认输出中出现预期诊断内容（不仅是命令行出现 `apiVersion`）。
  3. 回滚：删除对应 compilerOptions 项后 Clean 并重编。
  4. 注意：按 Debug/Release 分流配置，避免公共污染。

同源旧旗标

应用工程只按上方「怎么用」里的 Gradle 示例配置。下面列出编译器还认识的旧名字，避免对着旧文档混用。

优先级：Gradle DSL 与 CLI 配置的是同一 API 版本旋钮；工程里优先用 compilerOptions。

  • 推荐旗标：compilerOptions.apiVersion（键 apiVersion） — Gradle DSL（compilerOptions）。
  • 旧旗标（勿用）：-api-version <version>（键 api-version） — 旧编译器旗标；应用工程用本页推荐的 compilerOptions，不要再写一条 freeCompilerArgs。

默认行为 视情况

不写这个配置时，编译器会怎么处理？

此选项的默认值视情况而定（如目标平台或构建类型）。详见下方默认值说明。

未设则跟工具链 API 默认走。

相关文档

以下摘抄原文中与本配置最相关的段落，便于速读；完整上下文请点原文。

溯源与对照

状态
稳定（正式选项）
版本基线
2.2.21-1.0.0
定义位置类型
Gradle 插件 API（compilerOptions）
源码路径
libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinCommonCompilerOptions.kt 在仓库中打开