遷移至內建 Kotlin

Android Gradle 外掛程式 9.0 導入內建 Kotlin 支援功能，並預設啟用這項功能。也就是說，您不必再於建構檔案中套用 org.jetbrains.kotlin.android (或 kotlin-android) 外掛程式，即可編譯 Kotlin 來源檔案。由於 Kotlin 已內建於 AGP 中，建構檔案會更簡單，您也可以避免 AGP 與 kotlin-android 外掛程式之間的相容性問題。

啟用內建 Kotlin

您需要 AGP 9.0 以上版本，才能使用內建的 Kotlin 支援功能。 AGP 9.0 會為您套用 AGP 的所有模組啟用內建 Kotlin，因此您不需要採取任何動作。不過，如果您先前已在 gradle.properties 檔案中設定 android.builtInKotlin=false，停用內建 Kotlin，則必須移除該設定或將其設為 true。

內建 Kotlin 需要對專案進行一些變更，因此啟用內建 Kotlin 後，請按照後續步驟遷移專案。

遷移步驟

將專案從舊版 AGP 升級至 AGP 9.0，或手動啟用內建 Kotlin 後，您可能會看到下列錯誤訊息：

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

...或

Failed to apply plugin 'com.jetbrains.kotlin.android'
> The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0.

發生這個錯誤的原因是內建 Kotlin 需要對專案進行一些變更。如要解決這項錯誤，請按照下列步驟操作：

  1. 移除 kotlin-android 外掛程式
  2. 視需要遷移 kotlin-kapt 外掛程式
  3. 視需要遷移 android.kotlinOptions{} DSL
  4. 視需要遷移 kotlin.sourceSets{} DSL

1. 移除 kotlin-android 外掛程式

從套用外掛程式的模組層級建構檔案中，移除 org.jetbrains.kotlin.android (或 kotlin-android) 外掛程式。要移除的確切程式碼，取決於您是否使用版本目錄宣告外掛程式。

使用版本目錄

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

沒有任何版本目錄

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

然後從頂層建構檔案中移除外掛程式：

使用版本目錄

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

沒有任何版本目錄

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// Top-level build file
plugins {
    id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false
}

如果您使用版本目錄，請一併從版本目錄 TOML 檔案 (通常為 gradle/libs.versions.toml) 移除外掛程式定義：

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "KOTLIN_VERSION" }

2. 視需要遷移 kotlin-kapt 外掛程式

org.jetbrains.kotlin.kapt (或 kotlin-kapt) 外掛程式與內建 Kotlin 不相容。如果您使用 kapt，建議將專案遷移至 KSP。

如果還無法遷移至 KSP，請使用與 Android Gradle 外掛程式相同版本的 com.android.legacy-kapt 外掛程式，取代 kotlin-kapt 外掛程式。

舉例來說，使用版本目錄時，請依下列方式更新版本目錄 TOML 檔案：

[plugins]
android-application = { id = "com.android.application", version.ref = "AGP_VERSION" }

# Add the following plugin definition
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "AGP_VERSION" }

# Remove the following plugin definition
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "KOTLIN_VERSION" }

接著更新建構檔案：

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

3. 視需要遷移 android.kotlinOptions{} DSL

如果您使用 android.kotlinOptions{} DSL，則需要將其遷移至 kotlin.compilerOptions{} DSL。

舉例來說，請更新下列程式碼：

Kotlin

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

Groovy

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

...到新的 DSL：

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

4. 視需要遷移 kotlin.sourceSets{} DSL

使用 kotlin-android 外掛程式時，AGP 可讓您使用 android.sourceSets{} DSL 或 kotlin.sourceSets{} DSL 新增其他 Kotlin 來源目錄。使用 android.sourceSets{} DSL 時，您可以將目錄新增至 AndroidSourceSet.kotlin 集或 AndroidSourceSet.java 集。

使用內建 Kotlin 時，唯一支援的選項是使用 android.sourceSets{} DSL，將目錄新增至 AndroidSourceSet.kotlin 集合。如果使用不支援的選項，請按照下列方式遷移：

Kotlin

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

Groovy

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

如要將 Kotlin 來源目錄新增至特定變數，或目錄是由工作產生，可以使用變數 API 中的 addStaticSourceDirectory 或 addGeneratedSourceDirectory 方法：

Kotlin

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Groovy

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

回報問題

完成上述步驟後，如果仍遇到問題，請參閱問題 #438678642 中的已知問題，並視需要提供意見回饋。

停用內建 Kotlin

如果無法遷移專案以使用內建 Kotlin，請在 gradle.properties 檔案中設定 android.builtInKotlin=false，暫時停用這項功能。這麼做時，建構作業會顯示警告，提醒您遷移至內建 Kotlin，因為在 AGP 10.0 之前，您無法在 AGP 9.x 的未來版本中停用內建 Kotlin。

準備好遷移專案後，請啟用內建 Kotlin，然後按照遷移步驟操作。

逐一遷移模組

您可以使用 android.builtInKotlin Gradle 屬性，為套用 AGP 的所有模組啟用或停用內建 Kotlin。

如果一次遷移所有模組有困難，可以一次遷移一個模組：

  1. 在 gradle.properties 檔案中設定 android.builtInKotlin=false，為所有模組停用內建 Kotlin。

  2. 將 com.android.built-in-kotlin 外掛程式套用至要啟用內建 Kotlin 的模組，並使用與 Android Gradle 外掛程式相同的版本。

  3. 請按照先前的遷移步驟，將這個模組遷移至內建 Kotlin。

  4. 遷移所有模組後，請移除建構檔案中的 gradle.properties android.builtInKotlin=false 設定和 com.android.built-in-kotlin 外掛程式。

可選擇性停用內建 Kotlin

Android Gradle 外掛程式 9.0 會為套用外掛程式的所有模組啟用內建 Kotlin。在大型專案中，如果模組沒有 Kotlin 來源，建議您選擇性停用內建 Kotlin。這會移除 Kotlin 編譯工作 (會造成少許建構效能成本)，以及對 Kotlin 標準程式庫的自動依附元件。

如要停用模組的內建 Kotlin，請在該模組的建構檔案中設定 enableKotlin = false：

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}