Kotlin Gradle plugin 中的编译器选项 Kotlin 的每一个发布版本都包含它所支持的各个编译目标的编译器: JVM, JavaScript, 以及 支持的平台的 原生二进制文件.
这些编译器会在以下情况下使用:
当你对你的 Kotlin 工程按下 Compile 或 Run 按钮时, 由 IDE 使用.
当你在控制台或在 IDE 内调用 gradle build
命令时, 由 Gradle 使用.
当你在控制台或在 IDE 内调用 mvn compile
或 mvn test-compile
, 由 Maven 使用.
你也可以从命令行手动运行 Kotlin 编译器, 详情请参见教程 使用命令行编译器 .
如何定义编译器选项 Kotlin 编译器带有很多选项, 用来定制编译过程.
Gradle DSL 可以对编译器选项进行全面的配置. 可以用于 Kotlin Multiplatform 和 JVM/Android 项目.
使用 Gradle DSL, 你可以在构建脚本的 3 个层级配置编译器选项:
更高层级中的设置会被成为更低层级中的约定(默认)设置:
在扩展层级中设置的编译器选项会成为编译目标层级选项的默认值, 包括共用源代码集, 例如 commonMain
, nativeMain
, 和 commonTest
.
在编译目标层级中设置的编译器选项会成为编译单元(task)层级选项的默认值, 例如 compileKotlinJvm
和 compileTestKotlinJvm
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 名.
有一些重要的细节需要注意:
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 时, 请使用相应的 Kotlin2JsCompile
和 KotlinCompileCommon
类型.
你可以查看 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 编译器所支持的选项完整列表如下:
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
属性. 如果你希望恢复 Kotlin Gradle DSL 中的某些选项, 请在 Youtrack 中 提出问题 .
通过 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