Kotlin Gradle plugin 中的编译器选项

最终更新: 2025/02/06

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 个层级配置编译器选项:

  • 扩展层级(Extension Level), 在 kotlin {} 代码块之内, 用于所有的编译目标和共用源代码集.

  • 编译目标层级(Target Level), 在特定的编译目标的代码块之内.

  • 编译单元层级(Compilation Unit Level), 通常在特定的编译任务之内.

Kotlin 编译器选项层级

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

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

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

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

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

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

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

tip

如果你是第 3 方 plugin 的开发者, 最好在项目层级适用你的配置, 以免发生配置覆盖的问题. 你可以使用新的 Kotlin plugin DSL 扩展类型 来实现. 建议你对这些配置编写明确的文档.

扩展层级(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 {

                }
            }
        }
    }
}

如果你想要配置 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("1.8")
    }
}

JVM 目标平台

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

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

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

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

  • android.kotlinOptions 和 kotlin.compilerOptions 配置代码块会相互覆盖. 只有最后出现的 (最下方的) 代码块会起作用.

  • 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)

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

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

配置所有的 Kotlin 编译任务

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

import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    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", ..., "22", "23". 参见 编译器选项的数据类型

"1.8"

noJdk

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

false

jvmTargetValidationMode

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

WARNING, ERROR, INFO

ERROR

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" (实验性功能)

warning

在未来的发布版中, 我们将会废弃 freeCompilerArgs 属性. 如果你希望恢复 Kotlin Gradle DSL 中的某些选项, 请在 Youtrack 中 提出问题.

设置 languageVersion 的示例

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

kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1)
    }
}

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

JavaScript 任务独有的属性

属性名称

描述

可以选择的值

默认值

friendModulesDisabled

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

false

main

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

"call", "noCall". 参见 编译器选项的数据类型

"call"

metaInfo

指定是否生成带有 metadata 的 .meta.js 和 .kjsm 文件. 用于创建库

true

moduleKind

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

"umd", "commonjs", "amd", "plain", "es". 参见 编译器选项的数据类型

"umd"

outputFile

指定编译结果输出的 *.js 文件

"<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js"

sourceMap

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

true

sourceMapEmbedSources

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

"never", "always", "inlining". 参见 编译器选项的数据类型

sourceMapNamesPolicy

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

"simple-names", "fully-qualified-names", "no". 参见 编译器选项的数据类型

"simple-names"

sourceMapPrefix

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

target

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

"v5"

"v5"

typedArrays

将基本类型数组转换为 JS 的有类型数组

true

编译器选项的数据类型

有些 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)

下一步做什么?

学习: