Kotlin Gradle 插件中的编译器选项

每个 Kotlin 的发行版本都包含对于以下目标代码的编译器： JVM、JavaScript，以及支持平台的本地二进制文件。

这些编译器会在这些步骤中被调用：

• IDE，当你在你的 Kotlin 项目上点击编译或运行按钮时。
• Gradle，当你在控制台或者 IDE 上调用 gradle build 命令时。
• Maven，当你在控制台或者 IDE 上调用 mvn compile 或者 mvn test-compile命令时。

你也可以用命令行手动调用 Kotlin 编译器， 详见使用命令行编译器教程。

配置选项

Kotlin 编译器有一系列用于控制编译过程的参数。

The Gradle DSL allows comprehensive configuration of compiler options. It is available for Kotlin Multiplatform and JVM/Android projects.

With the Gradle DSL, you can configure compiler options within the build script at three levels:

• Extension level, in the kotlin {} block for all targets and shared source sets.
• Target level, in the block for a specific target.
• Compilation unit level, usually in a specific compilation task.

The settings at a higher level are used as a convention (default) for a lower level:

• Compiler options set at the extension level are the default for target-level options, including shared source sets like commonMain, nativeMain, and commonTest.
• Compiler options set at the target level are the default for options at the compilation unit (task) level, like compileKotlinJvm and compileTestKotlinJvm tasks.

In turn, configurations made at a lower level override related settings at a higher level:

• Task-level compiler options override related configurations at the target or the extension level.
• Target-level compiler options override related configurations at the extension level.

To find out which level of compiler arguments is applied to the compilation, use the DEBUG level of Gradle logging. For JVM and JS/WASM tasks, search for the "Kotlin compiler args:" string within the logs; for Native tasks, search for the "Arguments =" string.

If you're a third-party plugin author, it's best to apply your configuration on the project level to avoid overriding issues. You can use the new Kotlin plugin DSL extension types for this. It's recommended that you document this configuration on your side explicitly.

{style="tip"}

Extension level

You can configure common compiler options for all the targets and shared source sets in the compilerOptions {} block at the top level:

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

Target level

You can configure compiler options for the JVM/Android target in the compilerOptions {} block inside the target {} block:

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

In Kotlin Multiplatform projects, you can configure compiler options inside the specific target. For example, jvm { compilerOptions {}}. For more information, see Multiplatform Gradle DSL reference.

Compilation unit level

You can configure compiler options for a specific compilation unit or task in a compilerOptions {} block inside the task configuration:

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

You can also access and configure compiler options at a compilation unit level via KotlinCompilation:

kotlin {
    target {
        val main by compilations.getting {
            compileTaskProvider.configure {
                compilerOptions {

                }
            }
        }
    }
}

If you want to configure a plugin of a target different from JVM/Android and Kotlin Multiplatform, use the compilerOptions {} property of the corresponding Kotlin compilation task. The following examples show how to set this configuration up in both Kotlin and Groovy DSLs:

【Kotlin】

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

【Groovy】

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

面向 JVM

As explained before, you can define compiler options for your JVM/Android projects at the extension, target, and compilation unit levels (tasks).

Default JVM 环境下的编译任务，对于生产代码叫做 compileKotlin，而对于测试代码则叫做 compileTestKotlin。对于自定义源代码集（source set），这些任务命名遵循 compile＜Name＞Kotlin 模式。

You can see the list of Android compilation tasks by running the gradlew tasks --all command in the terminal and searching for compile*Kotlin task names in the Other tasks group.

有几点是需要注意的：

• android.kotlinOptions 和 kotlin.compilerOptions 这两个配置会相互覆写。只有最新（即最下面）的一个会生效。
• kotlin.compilerOptions 会影响项目中所有 Kotlin 编译任务的配置。
• 对于那些应用到 kotlin.compilerOptions 的任务，你可以通过 tasks.named("compileKotlin") { }（或者 tasks.withType().configureEach { }）来覆写配置。

面向 JavaScript

JavaScript 的编译任务，对于生产代码叫做 compileKotlinJs，对于测试代码叫做 compileTestKotlinJs。 对于自定义源代码集（source set），这些任务命名遵循 compile＜Name＞KotlinJs 模式。

要配置单个任务，请使用其名称：

【Kotlin】

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

val compileKotlin: KotlinCompilationTask<*> by tasks

compileKotlin.compilerOptions.suppressWarnings.set(true)

【Groovy】

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        suppressWarnings = true
    }
}

请注意，对于 Gradle Kotlin DSL，首先从项目的 tasks 中获取任务。

相应地，为 JS 与公共目标使用类型 Kotlin2JsCompile 与 KotlinCompileCommon。

You can see the list of JavaScript compilation tasks by running the gradlew tasks --all command in the terminal and searching for compile*KotlinJS task names in the Other tasks group.

All Kotlin compilation tasks

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

【Kotlin】

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

tasks.named>("compileKotlin").configure {
    compilerOptions { /*……*/ }
}

【Groovy】

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions { /*……*/ }
}

所有编译器选项

这里列出了 Gradle 编译器的完整选项列表：

常规属性

JVM 特有的属性

JVM 与 JavaScript 的公共属性

我们计划在今后的发行版本中将freeCompilerArgs选项弃用。如果你因此无法在 Kotlin Gradle DSL 中配置某些选项 请提出一个 Issue。

{style="warning"}

通过 freeCompilerArgs 选项配置额外的参数的示例

通过使用 freeCompilerArgs 属性来应用包括实验性参数在内的额外编译器参数。 可以在这个属性中加入一个单独的编译器参数或者一个编译器参数的列表。

【Kotlin】

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

kotlin {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        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"
            )
        ) 
    }
}

【Groovy】

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion = KotlinVersion.KOTLIN_2_1
        jvmTarget = JvmTarget.JVM_1_8

        // 单个实验性参数
        freeCompilerArgs.add("-Xexport-kdoc")

        // 单个附加参数，可以是键值对
        freeCompilerArgs.add("-Xno-param-assertions")

        // 参数列表
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

The freeCompilerArgs attribute is available at the extension, target, and compilation unit (task) levels.

{style="tip"}

设置 languageVersion 的示例

要设置语言的版本，请使用如下格式的语法：

【Kotlin】

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

【Groovy】

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

另见编译器选项的类型。

JavaScript 特有的属性

编译器选项的类型

一些 compilerOptions 使用独有的类型来替代字符串类型

下一步做什么？

了解更多关于：

• Kotlin Multiplatform DSL reference.
• 增量编译、缓存支持、构建日志以及 Kotlin 守护进程。
• Gradle 的基础知识和特性。
• 对 Gradle 插件变体的支持。