跳至主要内容

Kotlin Gradle 外掛程式中的編譯器選項

每個 Kotlin 版本都包含支援目標的編譯器： JVM、JavaScript 和 支援平台 的原生二進制檔案。

這些編譯器被以下項目使用：

  • IDE，當您點擊 Kotlin 專案的 Compile（編譯）或 Run（執行）按鈕時。
  • Gradle，當您在控制台或 IDE 中呼叫 gradle build 時。
  • Maven，當您在控制台或 IDE 中呼叫 mvn compile 或 mvn test-compile 時。

您也可以從命令行手動執行 Kotlin 編譯器，如使用命令行編譯器教學課程中所述。

如何定義選項​

Kotlin 編譯器有多個選項，可用於客製化編譯過程。

Gradle DSL 允許對編譯器選項進行全面的配置。它適用於 Kotlin Multiplatform 和 JVM/Android 專案。

透過 Gradle DSL，您可以在建構腳本中的三個層級配置編譯器選項：

  • Extension level（擴展層級），在適用於所有目標和共享原始碼集的 kotlin {} 區塊中。
  • Target level（目標層級），在特定目標的區塊中。
  • Compilation unit level（編譯單元層級），通常在特定的編譯任務中。
Kotlin 編譯器選項層級

較高層級的設定將被用作較低層級的慣例（預設值）：

  • 在擴展層級設定的編譯器選項是目標層級選項（包括共享原始碼集，如 commonMain、nativeMain 和 commonTest）的預設值。
  • 在目標層級設定的編譯器選項是編譯單元（任務）層級選項（如 compileKotlinJvm 和 compileTestKotlinJvm 任務）的預設值。

反過來，在較低層級所做的配置會覆蓋較高層級的相關設定：

  • 任務層級的編譯器選項會覆蓋目標層級或擴展層級的相關配置。
  • 目標層級的編譯器選項會覆蓋擴展層級的相關配置。

要了解哪個層級的編譯器參數應用於編譯，請使用 Gradle logging 的 DEBUG 層級。 對於 JVM 和 JS/WASM 任務，請在日誌中搜尋 "Kotlin compiler args:" 字串；對於 Native 任務， 請搜尋 "Arguments =" 字串。

提示

如果您是第三方外掛程式作者，最好的方式是在專案層級應用您的配置，以避免覆蓋問題。您可以為此使用新的 Kotlin plugin DSL extension types。建議您在您這一側明確記錄此配置。

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 reference。

Compilation unit level（編譯單元層級）​

您可以在任務配置內的 compilerOptions {} 區塊中為特定的編譯單元或任務配置編譯器選項：

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

您也可以透過 KotlinCompilation 在編譯單元層級存取和配置編譯器選項：

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

                }
            }
        }
    }
}

如果您想配置與 JVM/Android 和 Kotlin Multiplatform 不同的目標的外掛程式， 請使用相應 Kotlin 編譯任務的 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)
    }
}

Target the JVM（以 JVM 為目標）​

如先前所述，您可以在擴展、目標和編譯單元層級（任務）為您的 JVM/Android 專案定義編譯器選項。

預設的 JVM 編譯任務對於生產程式碼稱為 compileKotlin，對於測試程式碼稱為 compileTestKotlin。 自定義原始碼集的任務根據其 compile<Name>Kotlin 模式命名。

您可以透過在終端機中執行 gradlew tasks --all 命令，並在 Other tasks（其他任務）群組中搜尋 compile*Kotlin 任務名稱來查看 Android 編譯任務的列表。

需要注意的一些重要細節：

  • android.kotlinOptions 和 kotlin.compilerOptions 配置區塊會互相覆蓋。最後（最低）的區塊生效。
  • kotlin.compilerOptions 配置專案中的每個 Kotlin 編譯任務。
  • 您可以使用 tasks.named<KotlinJvmCompile>("compileKotlin") { }（或 tasks.withType<KotlinJvmCompile>().configureEach { }）方法覆蓋 kotlin.compilerOptions DSL 所應用的配置。

Target JavaScript（以 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 中取得任務。

分別為 JS 和通用目標使用 Kotlin2JsCompile 和 KotlinCompileCommon 類型。

您可以透過在終端機中執行 gradlew tasks --all 命令，並在 Other tasks（其他任務）群組中搜尋 compile*KotlinJS 任務名稱來查看 JavaScript 編譯任務的列表。

All Kotlin compilation tasks（所有 Kotlin 編譯任務）​

也可以配置專案中的所有 Kotlin 編譯任務：

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

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

All compiler options（所有編譯器選項）​

以下是 Gradle 編譯器的完整選項列表：

Common attributes（通用屬性）​

Name（名稱）Description（描述）Possible values（可能的值）Default value（預設值）
optIn用於配置 opt-in compiler arguments（選擇加入編譯器參數）列表的屬性listOf( /* opt-ins */ )emptyList()
progressiveMode啟用 progressive compiler mode（漸進式編譯器模式）true, falsefalse
extraWarnings如果為 true，啟用 additional declaration, expression, and type compiler checks（額外的宣告、表達式和類型編譯器檢查），這些檢查會發出警告true, falsefalse

Attributes specific to JVM（特定於 JVM 的屬性）​

Name（名稱）Description（描述）Possible values（可能的值）Default value（預設值）
javaParameters為 Java 1.8 反射生成方法參數的元資料false
jvmTarget生成的 JVM 位元組碼的目標版本"1.8", "9", "10", ..., "22", "23"。另請參閱 Types for compiler options（編譯器選項的類型）"1.8"
noJdk不要自動將 Java 運行時包含到類別路徑中false
jvmTargetValidationMode
  • 驗證 Kotlin 和 Java 之間的 JVM target compatibility（JVM 目標兼容性）
  • KotlinCompile 類型的任務的屬性。
    		• WARNING, ERROR, IGNOREERROR

    Attributes common to JVM and JavaScript（JVM 和 JavaScript 共有的屬性）​

    Name（名稱）Description（描述）Possible values（可能的值）Default value（預設值）
    allWarningsAsErrors如果有任何警告，報告錯誤false
    suppressWarnings不要產生警告false
    verbose啟用詳細記錄輸出。僅當啟用 Gradle debug log level enabled（Gradle 偵錯記錄層級）時才有效false
    freeCompilerArgs額外的編譯器參數列表。您也可以在此處使用實驗性的 -X 參數。請參閱 example（範例）[]
    apiVersion將宣告的使用限制為來自指定版本的捆綁庫的宣告"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 中遺漏了一些選項， 請提交 issue。

    Example of additional arguments usage via freeCompilerArgs （透過 freeCompilerArgs 使用其他參數的範例）​

    使用 freeCompilerArgs 屬性來提供額外的（包括實驗性的）編譯器參數。 您可以將單個參數或參數列表新增到此屬性：

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

    kotlin {
        compilerOptions {
            // Specifies the version of the Kotlin API and the JVM target（指定 Kotlin API 和 JVM 目標的版本）
            apiVersion.set(KotlinVersion.KOTLIN_2_1)
            jvmTarget.set(JvmTarget.JVM_1_8)
            
            // Single experimental argument（單個實驗性參數）
            freeCompilerArgs.add("-Xexport-kdoc")

            // Single additional argument（單個額外參數）
            freeCompilerArgs.add("-Xno-param-assertions")

            // List of arguments（參數列表）
            freeCompilerArgs.addAll(
                listOf(
                    "-Xno-receiver-assertions",
                    "-Xno-call-assertions"
                )
            ) 
        }
    }

    freeCompilerArgs 屬性在 extension（擴展層級）、target（目標層級）和 compilation unit (task)（編譯單元（任務）層級）可用。

    Example of setting languageVersion （設定 languageVersion 的範例）​

    要設定語言版本，請使用以下語法：

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

    另請參閱 Types for compiler options（編譯器選項的類型）。

    Attributes specific to JavaScript（特定於 JavaScript 的屬性）​

    Name（名稱）Description（描述）Possible values（可能的值）Default value（預設值）
    friendModulesDisabled禁用內部宣告匯出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產生源地圖（source map）false
    sourceMapEmbedSources將源文件嵌入到源地圖中JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER, JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYSnull
    sourceMapNamesPolicy將您在 Kotlin 程式碼中宣告的變數和函數名稱新增到源地圖中。有關行為的更多資訊，請參閱我們的 compiler reference（編譯器參考）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""es5"
    useEsClasses讓生成的 JavaScript 程式碼使用 ES2015 類別。在使用 ES2015 目標時預設啟用null

    Types for compiler options（編譯器選項的類型）​

    某些 compilerOptions 使用新的類型而不是 String 類型：

    Option（選項）Type（類型）Example（範例）
    jvmTargetJvmTargetcompilerOptions.jvmTarget.set(JvmTarget.JVM_11)
    apiVersion and languageVersionKotlinVersioncompilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_1)
    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)

    What's next?（下一步是什麼？）​

    瞭解更多關於：