迁移到内置 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，因此您无需执行任何操作即可启用它。不过，如果您之前 选择停用内置 Kotlin，则需要移除该设置或将其设置为 true。android.builtInKotlin=falsegradle.properties

内置 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）插件的模块级 build 文件中移除该插件。 要移除的确切代码取决于 您是否使用 版本目录 来声明插件。

使用版本目录

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

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

使用版本目录

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，请将 kotlin-kapt 插件替换为 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 文件：

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 源目录添加到特定变体，或者该 目录由任务生成，则可以在 addStaticSourceDirectory 或 addGeneratedSourceDirectory 方法 在 变体 API：

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 以暂时停用它。 这样做时，build 会显示一条警告，提醒您迁移到内置 Kotlin，因为您将无法在 AGP 10.0 中停用内置 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 设置以及 build 文件中的 com.android.built-in-kotlin 插件。

选择性停用内置 Kotlin 的选项

Android Gradle 插件 9.0 为应用它的所有模块启用了内置 Kotlin。 我们建议您针对大型项目中没有 Kotlin 源的模块选择性停用内置 Kotlin。 这样既可以移除 Kotlin 编译任务（该任务会产生少量 build 性能开销），也可以移除对 Kotlin 标准库的自动依赖项。

如需为模块停用内置 Kotlin，请在该模块的 build 文件中设置 enableKotlin = false：

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}