遷移至內建 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，則必須移除該設定或將 android.builtInKotlin=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. 視需要遷移 kotlinOptions{} 區塊

1. 移除 kotlin-android 外掛程式

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

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

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

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

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

接著，從頂層建構檔案中移除外掛程式：

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

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

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

// 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 相容。您需要使用與目前 Android Gradle 外掛程式相同的版本，將這個外掛程式替換為 com.android.legacy-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" }

接著更新建構檔案：

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

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

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

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

3. 視需要遷移 kotlinOptions{} 區塊

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

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

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

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

...to the new DSL:

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

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

回報問題

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

停用內建 Kotlin

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

逐一遷移模組

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

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

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

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

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

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