Gradle KTS — 是什么，适用于 Gradle 的 Kotlin DSL 及语法

什么是 Gradle KTS？

Gradle KTS 是 Kotlin DSL（领域特定语言），为编写 Gradle 配置文件提供了 Groovy 的替代方案。开发人员使用 Kotlin 而不是 Groovy 语法 — 一种严格类型化的语言，可以在编译阶段检查配置的正确性。KTS 于 2018 年在 Gradle 5.0 中作为实验性功能首次引入，并在 Gradle 6.0 中达到稳定。

KTS 的主要目标是消除 Groovy 在构建脚本中的缺点。Groovy 是一种动态类型语言，其中的配置错误仅在运行时执行任务时才会出现。KTS 凭借 Kotlin 的静态类型，可以在代码编辑阶段检测到同样的错误。此外，KTS 提供对 Gradle API 的访问，并附带完整的类型文档，这大大简化了复杂配置块的学习和使用。

KTS 生态系统得到所有主要工具的支持：Android Studio、IntelliJ IDEA、带有 Kotlin 插件的 VS Code 和 Gradle Build Tool。所有现代插件（Android Gradle Plugin、Kotlin Multiplatform、Protobuf、Compose）都提供具有显式类型的 Kotlin 友好 API，这使得 KTS 成为新项目的首选。

Gradle KTS 的工作原理

Gradle KTS 使用 Kotlin 编译器处理 .gradle.kts 文件。Gradle 识别扩展名并将脚本传递给 Kotlin 脚本引擎，该引擎将它们编译成类。然后这些类由 Gradle 执行以构建项目模型。与 Groovy 的关键区别：KTS 脚本是预先编译的，而不是动态解释的，这可以在任务开始执行之前检测错误。

KTS 的架构基于 kotlin-scripting。每个 .gradle.kts 文件都是一个 Kotlin 脚本，隐式导入了 Gradle API。开发人员可以使用任何 Kotlin 结构：扩展函数、lambda、数据类，甚至在构建脚本中声明辅助函数。Gradle 提供了一组扩展函数用于块的类型化配置：dependencies、android、kotlin 等。

plugins {
    id("com.android.application") version "8.4.0"
    kotlin("android") version "2.0.21"
}

android {
    namespace = "com.itsectr.app"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.itsectr.app"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0.0"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.core:core-ktx:1.13.1")
}

KTS 中的类型转换

KTS 和 Groovy 之间的关键区别之一是与类型的使用方式。在 Groovy 中，所有配置都接受 Object，而在 KTS 中则是具体的 Kotlin 类型。例如，compileSdk 接受 Int 而不是字符串。这消除了与错误类型相关的错误：在 Groovy 中 compileSdk 34 和 compileSdk “34” 的工作方式相同，而在 KTS 中只有第一种方式有效。这种严格性使配置更可预测且更易于文档化。

Gradle KTS 与 Groovy：对比

Groovy 是 Gradle 的原始 DSL，并继续保持完全支持。然而，KTS 提供了一系列优势，使其成为新项目的推荐选择。静态类型、更好的 IDE 编辑性能和更严格的语法是迁移到 KTS 的主要原因。同时，Groovy 在简单配置方面保留了简洁性的优势。

KTS 和 Groovy 在脚本编译后的构建性能几乎相同。KTS 脚本在首次启动或清除缓存后编译时间较长，但后续构建的运行速度与 Groovy 脚本相同。Gradle 将编译后的 KTS 脚本缓存在构建目录中，因此重新编译仅在脚本更改时发生。

2026 年在 KTS 和 Groovy 之间选择是明确的：对于新项目 — KTS。Google、JetBrains 和 Gradle 都推荐所有新项目使用 KTS。Groovy 仍然适用于维护遗留项目，在这些项目中，由于配置量或与 KTS 不兼容的特定插件，迁移是不切实际的。

代码示例：KTS 中的构建脚本

让我们看看 KTS 中针对 Android、Kotlin Multiplatform 和 Compose Multiplatform 的典型配置块。Android 项目 使用 KTS 需要在 buildTypes 和 productFlavors 的配置中显式指定类型。下面的示例展示了具有两个 flavour 的应用程序配置。

android {
    buildTypes {
        val release = getByName("release") {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        getByName("debug") {
            applicationIdSuffix = ".debug"
        }
    }

    flavorDimensions += "version"
    productFlavors {
        register("demo") {
            dimension = "version"
            versionNameSuffix = "-demo"
        }
        register("full") {
            dimension = "version"
        }
    }
}

对于 Kotlin Multiplatform，KTS 是必需的 — Groovy 不能正确支持多平台模块的配置。KMM 模块的配置包括目标平台和 source set 的设置。下面的示例展示了带有 iOS 和 Android 的共享模块配置。

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = "17"
            }
        }
    }

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
        androidMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
        }
    }
}

辅助函数和自定义任务

KTS 允许在构建脚本中声明 Kotlin 辅助函数。这对于重复配置特别方便，例如签名配置或版本管理。由于静态类型，这些函数可以在编译阶段进行参数检查，从而在发布到 Google Play 之前消除签名配置中的错误。

fun Project.configureSigning() {
    android {
        signingConfigs {
            register("release") {
                storeFile = file("release.keystore")
                storePassword = System.getenv("KEYSTORE_PASSWORD")
                keyAlias = System.getenv("KEY_ALIAS")
                keyPassword = System.getenv("KEY_PASSWORD")
            }
        }
    }
}

// 在 build.gradle.kts 中的使用
configureSigning()

从 Groovy 迁移到 KTS

迁移 从 Groovy 到 KTS — 是一个可以逐步执行的过程。Gradle 支持混合项目，其中部分模块使用 Groovy (build.gradle)，部分使用 KTS (build.gradle.kts)。settings.gradle 和根 build.gradle 可以首先转换，因为它们不依赖于模块的插件。Google 建议从 settings.gradle.kts 开始迁移，然后是根 build.gradle.kts，最后才是模块。

迁移的主要步骤包括：用 lambda 替换闭包语法、添加 = 符号进行赋值、用类型化常量替换字符串键以及对变量进行显式类型化。Android Studio 为简单块提供自动的 Groovy → KTS 转换，但具有嵌套闭包的复杂配置需要手动重写。

迁移时的典型问题包括没有 Kotlin 等效项的 Groovy 方法的隐式调用，以及不提供 Kotlin 友好 API 的插件。对于第一个问题，Gradle 通过 withGroovyBuilder 提供兼容性 — 一种允许从 KTS 调用 Groovy 方法的机制。对于第二个问题 — 需要等待插件更新，或在完全迁移之前在 Groovy 模块中使用它。

适用于 Kotlin Multiplatform 的 Gradle KTS

Kotlin Multiplatform 是 KTS 作为强制性要求的主要项目。kotlin multiplatform 插件提供了用于配置目标平台、source set 和框架二进制文件的扩展，这些扩展只能通过 Kotlin DSL 使用。Groovy 不能正确支持多平台配置，因此 KMM 项目专门使用 KTS。

KTS 中的 KMM 配置包括非标准块：用于指定平台的 kotlin.target、用于组织通用和平台特定代码的 kotlin.sourceSets、用于与 CocoaPods 集成的 kotlin.cocoapods 以及用于选择 JDK 的 kotlin.jvmToolchain。每个块都有严格类型化的 API，在 Android Studio 中具有自动补全功能，这对于具有多个平台的复杂 KMM 项目的配置特别有价值。

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    cocoapods {
        summary = "Shared Kotlin module"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = false
        }
        pod("Alamofire") {
            version = "5.9"
        }
    }
}

由于 KTS 的静态类型，KMM 开发人员可以获得 source set 和依赖项的自动补全、框架配置的类型检查以及平台名称的重构能力。KTS 还简化了调试：KMM 配置中的错误显示为 Kotlin 编译错误并带有易于理解的消息，这与 Groovy 不同，在 Groovy 中错误可能一直隐藏到 Gradle 任务执行时才显现。