Kotlin 语言参考文档 中文版 Help

Kotlin Gradle plugin 中的编译器选项

Kotlin 的每一个发布版本都包含它所支持的各个编译目标的编译器: JVM, JavaScript, 以及 支持的平台的 原生二进制文件.

这些编译器会在以下情况下使用:

  • 当你对你的 Kotlin 工程按下 CompileRun 按钮时, 由 IDE 使用.

  • 当你在控制台或在 IDE 内调用 gradle build 命令时, 由 Gradle 使用.

  • 当你在控制台或在 IDE 内调用 mvn compilemvn test-compile, 由 Maven 使用.

你也可以从命令行手动运行 Kotlin 编译器, 详情请参见教程 使用命令行编译器.

如何定义编译器选项

Kotlin 编译器带有很多选项, 用来定制编译过程.

Gradle DSL 可以对编译器选项进行全面的配置. 可以用于 Kotlin MultiplatformJVM/Android 项目.

使用 Gradle DSL, 你可以在构建脚本的 3 个层级配置编译器选项:

Kotlin 编译器选项层级

更高层级中的设置会被成为更低层级中的约定(默认)设置:

  • 在扩展层级中设置的编译器选项会成为编译目标层级选项的默认值, 包括共用源代码集, 例如 commonMain, nativeMain, 和 commonTest.

  • 在编译目标层级中设置的编译器选项会成为编译单元(task)层级选项的默认值, 例如 compileKotlinJvmcompileTestKotlinJvm task.

反过来, 更低层级中的设置会覆盖更高层级中的相关设置:

  • Task 层级编译器的选项会覆盖编译目标层级或扩展层级的相关配置.

  • 编译目标层级的编译器选项会覆盖扩展层级的相关配置.

要查找编译时使用了编译器参数的哪个层级, 请使用 DEBUG 级别的 Gradle logging. 对于 JVM 和 JS/WASM task, 请在 log 中查找 "Kotlin compiler args:" 字符串; 对于 Native task, 请查找 "Arguments =" 字符串.

扩展层级(Extension Level)

可以在最顶层的 compilerOptions {} 代码段之内, 对所有编译目标和共用源代码集配置共通的编译器选项:

kotlin { compilerOptions { optIn.add("kotlin.RequiresOptIn") } }

编译目标层级(Target Level)

可以在 target {} 代码段内的 compilerOptions {} 代码段之内, 对 JVM/Android 编译目标配置编译器选项:

kotlin { target { compilerOptions { optIn.add("kotlin.RequiresOptIn") } } }

在 Kotlin Multiplatform 项目中, 可以在特定的编译目标之内配置编译器选项. 例如, jvm { compilerOptions {}}. 详情请参见 Multiplatform Gradle DSL 参考文档.

编译单元层级(Compilation Unit Level)

可以在 task 配置内的 compilerOptions {} 代码段之内, 对特定的编译单元或 task 配置编译器选项:

tasks.named<KotlinJvmCompile>("compileKotlin"){ compilerOptions { optIn.add("kotlin.RequiresOptIn") } }

你也可以通过 KotlinCompilation 在编译单元层级访问并配置编译器选项:

kotlin { target { val main by compilations.getting { compileTaskProvider.configure { compilerOptions { optIn.add("kotlin.RequiresOptIn") } } } } }

如果你想要配置 JVM/Android 和 Kotlin Multiplatform 之外的编译目标 plugin, 请使用对应的 Kotlin 编译 task 的 compilerOptions {} 属性. 下面的示例演示在 Kotlin 和 Groovy DSL 中如何设置这个配置:

tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) { compilerOptions { apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0) } }
tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) { compilerOptions { apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0) } }

kotlinOptions {} 迁移到 compilerOptions {}

在 Kotlin 2.2.0 之前, 可以使用 kotlinOptions {} 代码段配置编译器选项. 由于从 Kotlin 2.0.0 开始 kotlinOptions {} 代码段已被废弃, 关于迁移构建脚本, 改为使用 compilerOptions {} 代码段, 本节提供一些指南和建议:

集中编译器选项并使用类型

只要有可能, 要尽量在 扩展层级(Extension Level) 配置编译器选项, 并在 编译单元层级(Compilation Unit Level), 对特定的 task 覆盖它们.

compilerOptions {} 代码段中不能使用原始字符串, 因此要转换为有类型的值. 例如, 如果你的配置如下:

plugins { kotlin("jvm") version "2.2.0" } tasks.withType<KotlinCompile>().configureEach { kotlinOptions { jvmTarget = "17" languageVersion = "2.1" apiVersion = "2.1" } }
plugins { id 'org.jetbrains.kotlin.jvm' version '2.2.0' } tasks.withType(KotlinCompile).configureEach { kotlinOptions { jvmTarget = '17' languageVersion = '2.1' apiVersion = '2.1' } }

迁移之后, 应该是:

plugins { kotlin("jvm") version "2.2.0" } kotlin { // 扩展层级 compilerOptions { jvmTarget = JvmTarget.fromTarget("17") languageVersion = KotlinVersion.fromVersion("2.1") apiVersion = KotlinVersion.fromVersion("2.1") } } // 在编译单元层级进行覆盖的示例 tasks.named<KotlinJvmCompile>("compileKotlin"){ compilerOptions { apiVersion = KotlinVersion.fromVersion("2.1") } }
plugins { id 'org.jetbrains.kotlin.jvm' version '2.2.0' } kotlin { // 扩展层级 compilerOptions { jvmTarget = JvmTarget.fromTarget("17") languageVersion = KotlinVersion.fromVersion("2.1") apiVersion = KotlinVersion.fromVersion("2.1") } } // 在编译单元层级进行覆盖的示例 tasks.named("compileKotlin", KotlinJvmCompile).configure { compilerOptions { apiVersion = KotlinVersion.fromVersion("2.1") } }

android.kotlinOptions 迁移

如果你的构建脚本之前使用了 android.kotlinOptions, 请迁移到 kotlin.compilerOptions. 无论是在扩展层级(Extension Level)还是在编译目标层级(Target Level).

例如, 如果你的 Android 项目配置如下:

plugins { id("com.android.application") kotlin("android") } android { kotlinOptions { jvmTarget = "17" } }
plugins { id 'com.android.application' id 'org.jetbrains.kotlin.android' } android { kotlinOptions { jvmTarget = '17' } }

请更新为:

plugins { id("com.android.application") kotlin("android") } kotlin { compilerOptions { jvmTarget = JvmTarget.fromTarget("17") } }
plugins { id 'com.android.application' id 'org.jetbrains.kotlin.android' } kotlin { compilerOptions { jvmTarget = JvmTarget.fromTarget("17") } }

此外, 如果你的 Kotlin Multiplatform 项目, 带有 Android 编译目标, 配置如下:

plugins { kotlin("multiplatform") id("com.android.application") } kotlin { androidTarget { compilations.all { kotlinOptions.jvmTarget = "17" } } }
plugins { id 'org.jetbrains.kotlin.multiplatform' id 'com.android.application' } kotlin { androidTarget { compilations.all { kotlinOptions { jvmTarget = '17' } } } }

请更新为:

plugins { kotlin("multiplatform") id("com.android.application") } kotlin { androidTarget { compilerOptions { jvmTarget = JvmTarget.fromTarget("17") } } }
plugins { id 'org.jetbrains.kotlin.multiplatform' id 'com.android.application' } kotlin { androidTarget { compilerOptions { jvmTarget = JvmTarget.fromTarget("17") } } }

迁移 freeCompilerArgs

  • 将所有的 += 操作替换为 add()addAll() 函数.

  • 如果使用了 -opt-in 编译器选项, 请在 KGP API 参考文档 中检查是否已经有专用的 DSL 可用, 如果有, 请改为使用 DSL.

  • 将所有的 -progressive 编译器选项迁移到使用专用的 DSL: progressiveMode.set(true).

  • 将所有的 -Xjvm-default 编译器选项迁移到 使用专用的 DSL: jvmDefault.set(). 选项的对应关系如下:

    之前

    之后

    -Xjvm-default=all-compatibility

    jvmDefault.set(JvmDefaultMode.ENABLE)

    -Xjvm-default=all

    jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)

    -Xjvm-default=disable

    jvmDefault.set(JvmDefaultMode.DISABLE)

例如, 如果你的配置如下:

kotlinOptions { freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn" freeCompilerArgs += listOf("-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all") }
kotlinOptions { freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn" freeCompilerArgs += ["-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all"] }

请迁移到:

kotlin { compilerOptions { optIn.add("kotlin.RequiresOptIn") freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes")) progressiveMode.set(true) jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY) } }
kotlin { compilerOptions { optIn.add("kotlin.RequiresOptIn") freeCompilerArgs.addAll(["-Xcontext-receivers", "-Xinline-classes"]) progressiveMode.set(true) jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY) } }

JVM 目标平台

如上文所述, 你可以对你的 JVM/Android 项目在扩展, 编译目标, 和编译单元层级(任务)定义编译器选项.

对于 JVM 目标平台, 编译产品代码的默认编译任务名为 compileKotlin, 编译测试代码的编译任务名为 compileTestKotlin. 针对自定义源代码集的编译任务名, 是与源代码集名称对应的 compile<Name>Kotlin.

要查看 Android 编译任务列表, 你可以在终端中运行 gradlew tasks --all 命令, 并在 Other tasks 组中查找 compile*Kotlin task 名.

有一些重要的细节需要注意:

  • kotlin.compilerOptions 会配置项目中所有的 Kotlin 编译任务.

  • 你可以使用 tasks.named<KotlinJvmCompile>("compileKotlin") { } (或 tasks.withType<KotlinJvmCompile>().configureEach { }) 来由覆盖 kotlin.compilerOptions DSL 提供的配置.

JavaScript 目标平台

对于 JavaScript 目标平台, 产品代码的编译任务名是 compileKotlinJs, 测试代码的编译任务名是 compileTestKotlinJs, 针对自定义源代码集的编译任务名, 是 compile<Name>KotlinJs.

要对单个编译任务进行配置, 请使用它的名称. 示例如下:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask // ... val compileKotlin: KotlinCompilationTask<*> by tasks compileKotlin.compilerOptions.suppressWarnings.set(true)
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask // ... tasks.named('compileKotlin', KotlinCompilationTask) { compilerOptions { suppressWarnings = true } }

注意, 使用 Gradle Kotlin DSL 时, 你应该先从编译工程的 tasks 属性得到编译任务.

编译 JavaScript 和 Common 时, 请使用相应的 Kotlin2JsCompileKotlinCompileCommon 类型.

你可以查看 JavaScript 编译任务的列表, 方法是在终端中运行 gradlew tasks --all 命令, 并搜索 Other tasks 组中的 compile*KotlinJS task 名称.

所有的 Kotlin 编译任务

也可以对项目中的所有 Kotlin 编译任务进行配置:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask // ... tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure { compilerOptions { /*...*/ } }
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask // ... tasks.named('compileKotlin', KotlinCompilationTask) { compilerOptions { /*...*/ } }

所有的编译器选项

Gradle 编译器所支持的选项完整列表如下:

共通属性

属性名称

描述

可以选择的值

默认值

optIn

配置 opt-in 编译器参数 列表

listOf( /* opt-ins */ )

emptyList()

progressiveMode

启用 渐进编译模式

true, false

false

extraWarnings

启用 额外的声明, 表达式, 和类型编译器检查, 如果检查结果为 true, 会产生警告

true, false

false

JVM 任务独有的属性

属性名称

描述

可以选择的值

默认值

javaParameters

为 Java 1.8 的方法参数反射功能生成 metadata

false

jvmTarget

指定编译输出的 JVM 字节码的版本

"1.8", "9", "10", ..., "23", "24". 参见 编译器选项的数据类型

"1.8"

noJdk

不要自动将 Java 运行库包含到 classpath 内

false

jvmTargetValidationMode

验证 Kotlin 和 Java 编译任务的 JVM 编译目标兼容性. 适用于 KotlinCompile 类型的任务.

WARNING, ERROR, IGNORE

ERROR

jvmDefault

控制接口中定义的函数如何编译为 JVM 上的默认方法

ENABLE, NO_COMPATIBILITY, DISABLE

ENABLE

JVM, 和 JavaScript 任务支持的共通属性

属性名称

描述

可以选择的值

默认值

allWarningsAsErrors

把警告作为错误来处理

false

suppressWarnings

不产生警告信息

false

verbose

输出详细的 log 信息. 只在 Gradle debug log 级别启用 时有效

false

freeCompilerArgs

指定额外的编译参数, 可以是多个. 这里也可以使用实验性的 -X 参数. 参见 示例

[]

apiVersion

只允许使用指定的版本的运行库中的 API

"1.8", "1.9", "2.0", "2.1", "2.2" (实验性功能)

languageVersion

指定源代码所兼容的 Kotlin 版本

"1.8", "1.9", "2.0", "2.1", "2.2" (实验性功能)

通过 freeCompilerArgs 使用额外参数的示例

可以使用 freeCompilerArgs 属性来指定额外的 (包括实验性的) 编译器参数. 你可以对这个属性添加单个参数, 也可以是多个参数的列表:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask // ... kotlin { compilerOptions { // 指定 Kotlin API 和 JVM 编译目标的版本 apiVersion.set(KotlinVersion.KOTLIN_2_1) jvmTarget.set(JvmTarget.JVM_1_8) // 单个实验性参数 freeCompilerArgs.add("-Xexport-kdoc") // 单个额外参数 freeCompilerArgs.add("-Xno-param-assertions") // 多个参数的列表 freeCompilerArgs.addAll( listOf( "-Xno-receiver-assertions", "-Xno-call-assertions" ) ) } }
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask // ... tasks.named('compileKotlin', KotlinCompilationTask) { compilerOptions { // 指定 Kotlin API 和 JVM 编译目标的版本 apiVersion = KotlinVersion.KOTLIN_2_1 jvmTarget = JvmTarget.JVM_1_8 // 单个实验性参数 freeCompilerArgs.add("-Xexport-kdoc") // 单个额外参数, 可以是 key-value 对 freeCompilerArgs.add("-Xno-param-assertions") // 多个参数的列表 freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"]) } }

设置 languageVersion 的示例

要设置语言版本, 请使用下面的语法:

kotlin { compilerOptions { languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1) } }
tasks .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) .configureEach { compilerOptions.languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1 }

参见 编译器选项的数据类型.

JavaScript 任务独有的属性

属性名称

描述

可以选择的值

默认值

friendModulesDisabled

指定是否关闭内部声明的输出

false

main

指定执行时是否调用 main 函数

JsMainFunctionExecutionMode.CALL, JsMainFunctionExecutionMode.NO_CALL

JsMainFunctionExecutionMode.CALL

moduleKind

指定编译器生成的 JS 模块类型

JsModuleKind.MODULE_AMD, JsModuleKind.MODULE_PLAIN, JsModuleKind.MODULE_ES, JsModuleKind.MODULE_COMMONJS, JsModuleKind.MODULE_UMD

null

sourceMap

指定是否生成源代码映射文件(source map)

false

sourceMapEmbedSources

指定是否将源代码文件嵌入到源代码映射文件中

JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYS

null

sourceMapNamesPolicy

将你在 Kotlin 代码中声明的变量和函数名称添加到源代码映射文件中. 详情请参见 编译器参考文档

JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NO

null

sourceMapPrefix

对源代码映射文件中的路径添加一个指定的前缀

null

target

指定生成的 JS 文件 的 ECMA 版本

"es5", "es2015"

"es5"

useEsClasses

Let generated JavaScript code use ES2015 classes. Enabled by default in case of ES2015 target usage

null

编译器选项的数据类型

有些 compilerOptions 使用新的数据类型, 而不是旧的 String 类型:

选项

数据类型

示例

jvmTarget

JvmTarget

compilerOptions.jvmTarget.set(JvmTarget.JVM_11)

apiVersion and languageVersion

KotlinVersion

compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_1)

main

JsMainFunctionExecutionMode

compilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL)

moduleKind

JsModuleKind

compilerOptions.moduleKind.set(JsModuleKind.MODULE_ES)

sourceMapEmbedSources

JsSourceMapEmbedMode

compilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING)

sourceMapNamesPolicy

JsSourceMapNamesPolicy

compilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES)

下一步做什么?

学习:

2025/08/04