迁移到内置 Kotlin

Android Gradle 插件 9.0 引入了内置 Kotlin 支持，并默认启用该支持。这意味着，您无需再在 build 文件中应用 org.jetbrains.kotlin.android（或 kotlin-android）插件来编译 Kotlin 源文件。借助内置 Kotlin，您的 build 文件会更简单，并且您可以避免 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）插件的模块级 build 文件中移除该插件。要移除的具体代码取决于您是否使用版本目录来声明插件。

// 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'
}

然后，从顶级 build 文件中移除该插件：

// 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 插件（如有必要）

如果您在 build 文件中使用 org.jetbrains.kotlin.kapt（或 kotlin-kapt），则此插件将无法与内置 Kotlin 兼容。您需要将此插件替换为 com.android.legacy-kapt 插件，并使用与当前 Android Gradle 插件相同的版本。

例如，使用版本目录时，请按如下方式更新版本目录 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" }

然后，更新 build 文件：

// 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"
    }
}

...到新的 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。这样做时，build 会显示一条警告，提醒您迁移到内置 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 设置以及 build 文件中的 com.android.experimental.built-in-kotlin 插件。