将 build 配置从 Groovy 迁移到 KTS

Kotlin 脚本 (KTS) 比 Groovy 更适合用于编写 Gradle 脚本，因为采用 Kotlin 编写的代码可读性更高，并且 Kotlin 提供了更好的编译时检查和 IDE 支持。Android Gradle 插件 4.0 支持在 Gradle build 配置中使用 KTS。

本页介绍了有关将 Android 应用的 Gradle build 文件从 Groovy 转换为 KTS 的基本信息。我们建议您按照所列顺序执行这些步骤。另请参阅 Gradle 的迁移指南和 Kotlin DSL Primer。 如果要迁移多个项目，请从最小的项目开始以便积累经验，然后再继续迁移。

常用术语

KTS：是指 Kotlin 脚本，这是 Gradle 在 build 配置文件中使用的一种 Kotlin 语言形式。Kotlin 脚本是可从命令行运行的 Kotlin 代码。

Kotlin DSL：主要是指 Android Gradle 插件 Kotlin DSL，有时也指底层 Gradle Kotlin DSL。

在讨论从 Groovy 迁移时，术语“KTS”和“Kotlin DSL”可以互换使用。换句话说，“将 Android 项目从 Groovy 转换为 KTS”与“将 Android 项目从 Groovy 转换为 Kotlin DSL”实际上是一个意思。

脚本文件命名

脚本文件扩展名取决于编写 build 文件所用的语言：

• 用 Groovy 编写的 Gradle build 文件使用 .gradle 文件扩展名。
• 用 Kotlin 编写的 Gradle build 文件使用 .gradle.kts 文件扩展名。

提示：在开始迁移之前，请为您的所有 build.gradle 和 settings.gradle 文件创建备份。

转换语法

Groovy 和 Kotlin 的语法之间存在一些普遍差异，因此您需要在 build 脚本中应用以下更改。

为方法调用添加圆括号

提示：首先，在更改文件扩展名之前，最好先在 Groovy 代码中添加圆括号。这样可以更轻松地转换为 Kotlin。

Groovy 允许您在方法调用中省略圆括号，而 Kotlin 则要求使用圆括号。如需迁移配置，请为这些类型的方法调用添加圆括号。以下代码展示了如何在 Groovy 中配置设置：

compileSdkVersion 30

以下是使用 Kotlin 编写的相同代码：

compileSdkVersion(30)

为分配调用添加 =

提示：在更改文件扩展名之前，请在 Groovy 代码中添加 =。这样可以更轻松地转换为 Kotlin。

Gradle Groovy DSL 允许您在分配属性时省略赋值运算符“=”，而 Kotlin 则要求使用它。以下代码展示了如何在 Groovy 中分配属性：

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

以下代码展示了如何在 Kotlin 中分配属性：

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

转换字符串

以下是 Groovy 和 Kotlin 在字符串方面的差异：

• 用于定义字符串的双引号：虽然 Groovy 允许使用单引号来定义字符串，但 Kotlin 要求使用双引号。

• 基于句点表达式的字符串插值：在 Groovy 中，对于句点表达式的字符串插值，您可以仅使用“$”前缀，但 Kotlin 要求您用大括号将句点表达式括起来。例如，在 Groovy 中，您可以使用如以下代码段所示的 $project.rootDir：

      myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
      

  不过，在 Kotlin 中，上述代码会针对 project（而非 project.rootDir）调用 toString()。如需获取根目录的值，请使用大括号括住 ${project.rootDir} 表达式：

      myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
      

  如需了解详情，请参阅 Kotlin 文档中的字符串模板。

重命名文件扩展名

请在迁移每个 build 文件的内容时将 .kts 添加到其文件扩展名后。例如，选择一个 build 文件（如 settings.gradle 文件）。将该文件重命名为 settings.gradle.kts，然后将其内容转换为 KTS。请确保您的项目在迁移每个 build 文件之后仍然可以编译。

请先迁移最小的文件以便积累经验，然后再继续。项目中可以混合使用 KTS 和 Groovy build 文件，因此您无需着急，可以小心细致地进行迁移。

将 def 替换为 val 或 var

将 def 替换为 val 或 var，这是在 Kotlin 中定义变量的方式。以下是 Groovy 中的变量声明：

def building64Bit = false

以下是使用 Kotlin 编写的相同代码：

val building64Bit = false

为布尔值属性添加 is 前缀

Groovy 会根据属性名称使用属性推导逻辑。对于布尔值属性 foo，其推导的方法可以是 getFoo、setFoo 或 isFoo。因此，在转换为 Kotlin 后，您需要为 Kotlin 不支持的推导方法更改属性名称。例如，对于 buildTypes DSL 布尔值元素，您需要为它们添加 is 前缀。以下代码展示了如何在 Groovy 中设置布尔值属性：

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

以下是 Kotlin 中的相同代码：请注意，这些属性带有 is 前缀。

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

转换列表和映射

Groovy 和 Kotlin 中的列表和映射使用不同的语法进行定义。Groovy 使用 []，而 Kotlin 使用 listOf 或 mapOf 显式调用集合创建方法。迁移时，请务必将 [] 替换为 listOf 或 mapOf。

以下是 Groovy（相对于 Kotlin）定义列表的方法：

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

以下是使用 Kotlin 编写的相同代码：

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

以下是 Groovy（相对于 Kotlin）定义映射的方法：

def myMap = [key1: 'value1', key2: 'value2']

以下是使用 Kotlin 编写的相同代码：

val myMap = mapOf("key1" to "value1", "key2" to "value2")

配置 build 类型

在 Kotlin DSL 中，只有调试和发布 build 类型是隐式提供的。所有其他自定义 build 类型都必须手动创建。

在 Groovy 中，您无需先创建就可以使用调试、发布和某些其他 build 类型。以下代码段展示了 Groovy 中具有 debug、release 和 benchmark build 类型的配置。

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

如需在 KTS 中创建等效配置，您必须显式创建 benchmark build 类型。

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

转换 plugins 块

在 Groovy 和 KTS 中应用插件的方式是类似的。在 KTS 和 Groovy 中，我们都建议使用 plugins {} 块，而不是将 buildscript 与 apply 结合使用来应用插件。

如果您在 build 文件中使用 plugins {} 块，Android Studio 将能够获知相关上下文信息，即使在构建失败时也是如此。此上下文有助于修复 KTS 文件，因为它让 Studio IDE 能够执行代码补全并提供其他有用的建议。

以下代码展示了当您使用 Gradle 版本目录时如何在 Groovy 中应用插件：

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

以下代码展示了如何在 Kotlin 中执行相同的操作：

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

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

以下代码展示了当您不使用 Gradle 版本目录时如何在 Groovy 中应用插件：

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

以下代码展示了如何在 Kotlin 中执行相同的操作：

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version '7.3.0' apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

如需详细了解 plugins {} 块，请参阅 Gradle 文档中的应用插件。

其他

如需了解 Kotlin 实现其他功能的代码示例，请参阅以下文档页面：

• 如果您有 ProGuard 配置，请参阅启用缩减、混淆和优化。
• 如果您有 signingConfig {} 块，请参阅从 build 文件中移除签名信息。
• 如果您使用项目全局属性，请参阅配置项目全局属性。

注意：虽然 Gradle 可让您在模块级别定义项目全局属性，但您应避免这样做，因为这样会导致共享这些属性的模块耦合。模块耦合使得以后将模块作为独立项目导出更加困难，并妨碍 Gradle 利用并行项目执行加快多模块 build。

已知问题

目前，一个已知问题是采用 KTS 的构建速度往往比采用 Groovy 慢。

如何报告问题

如需了解如何提供对问题进行分类所需的信息，请参阅构建工具和 Gradle bug 详细信息。然后，使用 Google 公开问题跟踪器来提交 bug。

更多资源

如需查看使用 KTS 编写的 Gradle build 文件的可运行示例，请参阅 GitHub 上的 Now in Android 示例应用。