Skip to content

Kotlin Gradle 插件中的编译器选项 ​

Kotlin 的每个版本都包含适用于受支持目标的编译器: JVM、JavaScript,以及适用于受支持平台的原生二进制文件。

这些编译器在以下场景中被调用:

  • 在 IDE 中点击 Kotlin 项目的 Compile 或 Run 按钮时。
  • 在控制台或 IDE 中调用 gradle build 时。
  • 在控制台或 IDE 中调用 mvn compile 或 mvn test-compile 时。

你也可以按照使用命令行编译器教程中所述,从命令行手动运行 Kotlin 编译器。

如何定义选项 ​

Kotlin 编译器提供了许多用于定制编译过程的选项。

Gradle DSL 支持对编译器选项进行全面配置。它适用于 Kotlin Multiplatform 和 JVM/Android 项目。

通过 Gradle DSL,你可以在构建脚本中的三个级别配置编译器选项:

Kotlin 编译器选项级别

较高层级的设置会作为较低层级的约定(默认值):

  • 在扩展级别设置的编译器选项是目标级别选项的默认值,包括像 commonMain、nativeMain 和 commonTest 这样的共享源集。
  • 在目标级别设置的编译器选项是编译单元(任务)级别选项的默认值,例如 compileKotlinJvm 和 compileTestKotlinJvm 任务。

反之,在较低层级所做的配置会覆盖较高层级的相关设置:

  • 任务级别的编译器选项会覆盖目标级别或扩展级别的相关配置。
  • 目标级别的编译器选项会覆盖扩展级别的相关配置。

要查看实际应用到编译中的是哪一级别的编译器实参,请使用 Gradle 的 DEBUG 级别日志。 对于 JVM 和 JS/WASM 任务,在日志中搜索 "Kotlin compiler args:" 字符串;对于 Native 任务,搜索 "Arguments =" 字符串。

如果你是第三方插件作者,最好在项目级别应用你的配置,以避免覆盖问题。为此,你可以使用全新的 Kotlin 插件 DSL 扩展类型。建议你在自己的文档中显式记录此配置。

扩展级别 ​

你可以在顶层的 compilerOptions {} 块中为所有目标和共享源集配置通用编译器选项:

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

目标级别 ​

你可以在 target {} 块内的 compilerOptions {} 块中为 JVM/Android 目标配置编译器选项:

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

在 Kotlin Multiplatform 项目中,你可以在具体目标内配置编译器选项。例如:jvm { compilerOptions {}}。更多信息请参阅 Multiplatform Gradle DSL 参考。

编译单元级别 ​

你可以在任务配置内的 compilerOptions {} 块中为特定的编译单元或任务配置编译器选项:

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

你还可以通过 KotlinCompilation 在编译单元级别访问和配置编译器选项:

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

如果你想为除 JVM/Android 和 Kotlin Multiplatform 之外的目标配置插件,请使用对应 Kotlin 编译任务的 compilerOptions {} 属性。以下示例展示了如何在 Kotlin 和 Groovy DSL 中完成此设置:

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

从 kotlinOptions {} 迁移到 compilerOptions {} ​

在 Kotlin 2.2.0 之前,你可以使用 kotlinOptions {} 块来配置编译器选项。由于 kotlinOptions {} 块自 Kotlin 2.0.0 起已弃用,本节提供了将构建脚本迁移为改用 compilerOptions {} 块的指南与建议:

集中管理编译器选项并使用类型化值 ​

只要可能,尽量在扩展级别配置编译器选项,并在编译单元级别针对特定任务进行重写。

在 compilerOptions {} 块中不能使用原始字符串,因此需要将其转换为类型化值。例如,如果原来是这样:

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}

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

tasks.withType(KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = '17'
        languageVersion = '2.4'
        apiVersion = '2.4'
    }
}

迁移后应为:

kotlin
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

plugins {
    kotlin("jvm") version "2.4.21"
}

kotlin {
    // 扩展级别
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.4")
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

// 在编译单元级别进行重写的示例
tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}
kotlin
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}

kotlin {
  // 扩展级别
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.4")
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

// 在编译单元级别进行重写的示例
tasks.named("compileKotlin", KotlinJvmCompile).configure {
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

迁移不再使用 android.kotlinOptions ​

如果你的构建脚本之前使用了 android.kotlinOptions,请迁移为改用 kotlin.compilerOptions。可以在扩展级别或目标级别进行配置。

例如,对于 Android 项目:

kotlin
plugins {
    id("com.android.application")
    kotlin("android")
}

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

android {
    kotlinOptions {
        jvmTarget = '17'
    }
}

更新为:

kotlin
plugins {
    id("com.android.application")
    kotlin("android")
}

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

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}

又例如,对于带有 Android 目标的 Kotlin Multiplatform 项目:

kotlin
plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

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

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = '17'
            }
        }
    }
}

更新为:

kotlin
plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilerOptions {
            jvmTarget = JvmTarget.fromTarget("17")
        }
    }
}
kotlin
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-compatibilityjvmDefault.set(JvmDefaultMode.ENABLE)
    -Xjvm-default=alljvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    -Xjvm-default=disablejvmDefault.set(JvmDefaultMode.DISABLE)

例如,如果原来是这样:

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

迁移为:

kotlin
kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
        freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes"))
        progressiveMode.set(true)
        jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    }
}
kotlin
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 模式命名。

你可以在终端中运行 gradlew tasks --all 命令,并在 Other tasks 分组中搜索 compile*Kotlin 任务名称,以查看 Android 编译任务列表。

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

  • kotlin.compilerOptions 会配置项目中的每个 Kotlin 编译任务。
  • 你可以通过 tasks.named<KotlinJvmCompile>("compileKotlin") { }(或 tasks.withType<KotlinJvmCompile>().configureEach { })方式来覆盖 kotlin.compilerOptions DSL 所应用的配置。

针对 JavaScript ​

JavaScript 编译任务在生产代码中名为 compileKotlinJs,在测试代码中名为 compileTestKotlinJs,对于自定义源集则为 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 和 common 目标使用 Kotlin2JsCompile 和 KotlinCompileCommon 类型。

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

所有 Kotlin 编译任务 ​

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

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

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

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

所有编译器选项 ​

以下是通过 Kotlin Gradle 插件可用的 Kotlin 编译器选项的完整列表:

通用属性 ​

名称说明可选值默认值
allWarningsAsErrors若有任何警告则报错false
apiVersion控制你的代码可以使用哪些 Kotlin API。更多信息请参阅 -api-version。"2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL)
extraWarnings启用额外的声明、表达式和类型编译器检查,若为 true 则输出警告true, falsefalse
freeCompilerArgs额外编译器实参的列表。你也可以在此处使用实验性的 -X 实参。参见示例[]
languageVersion控制编译期间可用的 Kotlin 语言功能和语法。更多信息请参阅 -language-version。"2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (EXPERIMENTAL)
optIn用于配置选择加入编译器实参列表的属性listOf( /* opt-ins */ )emptyList()
progressiveMode启用渐进式编译器模式true, falsefalse
suppressWarnings不生成警告false
verbose启用详细日志输出。仅在启用 Gradle debug 日志级别时生效false

我们计划在未来版本中弃用 freeCompilerArgs 属性。如果你在 Kotlin Gradle DSL 中发现缺少某些选项,请提交 issue。

通过 freeCompilerArgs 使用额外实参的示例 ​

使用 freeCompilerArgs 属性来提供额外的(包括实验性的)编译器实参。你可以向该属性添加单个实参或实参列表:

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

kotlin {
    compilerOptions {
        // 指定 Kotlin API 版本和 JVM 目标
        apiVersion.set(KotlinVersion.KOTLIN_2_4)
        jvmTarget.set(JvmTarget.JVM_1_8)
        
        // 单个实验性实参
        freeCompilerArgs.add("-Xexport-kdoc")

        // 单个额外实参
        freeCompilerArgs.add("-Xno-param-assertions")

        // 在模块路径上解析额外的根模块
        freeCompilerArgs.add("-Xadd-modules=jdk.incubator.vector")

        // 实参列表
        freeCompilerArgs.addAll(
            listOf(
                "-Xno-receiver-assertions",
                "-Xno-call-assertions"
            )
        ) 
    }
}
groovy
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
// ...

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // 指定 Kotlin API 版本和 JVM 目标
        apiVersion = KotlinVersion.KOTLIN_2_4
        jvmTarget = JvmTarget.JVM_1_8
        
        // 单个实验性实参
        freeCompilerArgs.add("-Xexport-kdoc")
        
        // 单个额外实参,可以是键值对
        freeCompilerArgs.add("-Xno-param-assertions")
        
        // 在模块路径上解析额外的根模块
        freeCompilerArgs.add("-Xadd-modules=jdk.incubator.vector")
        
        // 实参列表
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

freeCompilerArgs 属性可在扩展、目标以及编译单元(任务)级别使用。

设置 languageVersion 的示例 ​

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

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

某些属性使用自定义类型。更多信息请参阅编译器选项的类型。

JVM 专属属性 ​

名称说明可选值默认值
javaParameters为方法形参的 Java 1.8 反射生成元数据false
jvmTarget生成的 JVM 字节码的目标版本"1.8", "9", "10", ..., "25", 26"。另见编译器选项的类型"1.8"
jvmTargetValidationMode
  • 验证 Kotlin 与 Java 之间的 JVM 目标兼容性
  • 适用于 KotlinCompile 类型任务的属性。
WARNING, ERROR, IGNOREERROR
jvmDefault控制接口中声明的函数如何编译为 JVM 上的默认方法ENABLE, NO_COMPATIBILITY, DISABLEENABLE
noJdk不要自动将 Java 运行时引入类路径中false
-Xadd-modules(实验性)除初始模块外,解析指定的根模块。设置为 ALL-MODULE-PATH 值以解析模块路径上的所有模块。通过 freeCompilerArgs 传入的以逗号分隔的模块名称或 ALL-MODULE-PATH

JavaScript 专属属性 ​

名称说明可选值默认值
friendModulesDisabled禁用 internal 声明导出false
main指定在执行时是否应调用 main 函数JsMainFunctionExecutionMode.CALL, JsMainFunctionExecutionMode.NO_CALLJsMainFunctionExecutionMode.CALL
moduleKind编译器生成的 JS 模块类型JsModuleKind.MODULE_AMD, JsModuleKind.MODULE_PLAIN, JsModuleKind.MODULE_ES, JsModuleKind.MODULE_COMMONJS, JsModuleKind.MODULE_UMDnull
sourceMap生成源代码映射false
sourceMapEmbedSources将源文件嵌入到源代码映射中JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYSnull
sourceMapNamesPolicy将你在 Kotlin 代码中声明的变量和函数名称添加到源代码映射中。关于此行为的更多信息,请参阅我们的编译器参考JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES, JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NOnull
sourceMapPrefix为源代码映射中的路径添加指定前缀null
target为特定 ECMA 版本生成 JS 文件"es5", "es2015", "es2020""es5"
useEsClasses允许生成的 JavaScript 代码使用 ES2015 类。对于 ES2015 和 ES2020 目标默认启用null

编译器选项的类型 ​

部分 compilerOptions 使用自定义类型而不是 String 类型:

选项类型示例
apiVersion 与 languageVersionKotlinVersioncompilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_4)
jvmTargetJvmTargetcompilerOptions.jvmTarget.set(JvmTarget.JVM_11)
mainJsMainFunctionExecutionModecompilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL)
moduleKindJsModuleKindcompilerOptions.moduleKind.set(JsModuleKind.MODULE_ES)
sourceMapEmbedSourcesJsSourceMapEmbedModecompilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING)
sourceMapNamesPolicyJsSourceMapNamesPolicycompilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES)

后续步骤 ​

深入了解: