Gradle构建脚本选型：Groovy DSL与Kotlin DSL对比与迁移指南

上周碰到一个挺典型的求助：对方把网上抄来的构建脚本贴进项目，一段是 Groovy 的 implementation 'xxx'，一段是 Kotlin DSL 的 implementation("xxx")，编译结果时好时坏。很多人分不清 Gradle 里 Groovy DSL 和 Kotlin DSL 其实对应着两套不同的构建脚本语言，语法、报错方式、迁移成本都差很多。这篇文章就把它们放在一起做一次完整的对比，给正在选型或准备迁移的团队一个可以落地的参考。

单看标题里的“Groovy/Kotlin DSL对比”，有不少读者会以为这是个简单的语法偏好问题，实际接触下来你会发现，它牵扯到构建脚本的可维护性、IDE辅助能力、团队技能栈、插件兼容性，甚至构建性能。下面我会从两套 DSL 的由来开始，逐步拆到具体代码差异，再结合个人踩坑经验给出选型建议。

1. 同一个 Gradle，两套 DSL 的历史原因：这问题不是今天才有

1.1 从 XML 到脚本语言，Gradle 当初为什么选 Groovy

在 Gradle 出现之前，最主流的构建工具是 Ant 和 Maven。Ant 的构建文件是 XML，写起来冗长，逻辑稍微复杂一点就要靠一堆自定义任务；Maven 虽然引入了约定优于配置，但想在 pom.xml 里表达条件判断、循环、动态拼接版本号，依然非常痛苦，因为 XML 本质上只适合描述静态结构，不适合表达流程。

Gradle 的突破口就是“把构建脚本当成程序来写”。它默认选了 Groovy：这门语言和 Java 兼容，语法又比 Java 灵活得多，闭包、动态属性、字符串插值这些特性非常适合做外部 DSL。你可以在脚本里写循环、写函数、甚至临时定义一个类，而不需要为此切到另一种语言。也正因如此，Gradle 很快就和 Maven XML 拉开了体验差距。

但 Groovy 的优势同时也是它的隐患。动态语言对 IDE 不友好，属性拼错了、方法名写错了，往往要到配置阶段甚至执行阶段才会暴露。项目一大，构建脚本复杂起来，这种“运行期才报错”的体验会让人非常难受。

1.2 Kotlin 成熟后，Gradle 官方顺势推出第二套 DSL

Kotlin 在 Android 生态里普及之后，大量开发者开始希望“能用 Kotlin 的地方都用 Kotlin”，构建脚本也不例外。Gradle 官方在 2017 年前后开始引入 Kotlin DSL，也就是把 build.gradle 换成 build.gradle.kts，让你可以用 Kotlin 语法去编写构建脚本。

它和 Groovy DSL 在能力上是并列的：同一个项目里，你用 build.gradle 表达的逻辑，几乎都能用 build.gradle.kts 重写一遍。区别在于，Kotlin 是静态类型语言，编译期间能发现大量类型和属性错误，IDE 也能更准确地做自动补全和重构。之前我接手过一个几十个模块的工程，脚本里大量动态属性，用 Groovy 时谁也不敢随便改公共配置，迁到 Kotlin DSL 之后，公共配置里的拼写错误直接在编辑阶段就暴露了。

现在打开 Gradle 官网或者 Android Studio 的新项目模板，你会发现 .gradle.kts 的曝光率越来越高。很多新插件文档直接默认给 Kotlin DSL 示例，Groovy 示例反而要手动切换才看得到。但这不等于 Groovy 时代已经结束：存量项目里大量 .gradle 文件仍然在稳定运行，很多老开发也更习惯 Groovy 的简洁。于是选择困难就来了：新项目到底用哪套？老项目要不要迁？

2. 同一份构建配置，Groovy 与 Kotlin 在写法上的核心差异拆解

先放结论：两种 DSL 背后的能力近似，但语法习惯差异非常明显。不要觉得“会写 Groovy 就会写 Kotlin DSL”，也反过来认为“学过 Kotlin 就一定能顺利读懂 Groovy 脚本”。

2.1 基础语法差异：括号、引号和等号，这三处最容易让人懵

我先列一个最典型的对比，同样是配置一个 Java 项目：

groovy复制plugins {
    id 'java'
    id 'org.springframework.boot' version '2.7.18'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

同样的内容，用 Kotlin DSL 写是这样：

kotlin复制plugins {
    id("java")
    id("org.springframework.boot") version "2.7.18"
}

group = "com.example"
version = "0.0.1-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

注意到没有，最简单的地方反而是最容易写错的地方：

• Groovy 里字符串可以用单引号或双引号，Kotlin 里字符串必须用双引号，单引号表示单个字符。
• Groovy DSL 省略括号很常见，implementation 'xxx' 看着像普通文本，但在 Kotlin DSL 里方法调用必须带括号。
• 属性赋值在 Groovy 里有时能直接用命令式写法，在 Kotlin DSL 里往往必须写成 =。

所以从 Groovy 切到 Kotlin DSL 的第一个大坑就是：网上搜到的 Groovy 示例大概率不能直接粘贴，需要手动补括号、换引号。

再举一个仓库配置的例子。Groovy 经常这么写：

groovy复制repositories {
    maven {
        url 'https://repo.example.com/public'
    }
}

换成 Kotlin DSL，一般要写成：

kotlin复制repositories {
    maven {
        url = uri("https://repo.example.com/public")
    }
}

为什么不能照搬？因为 Kotlin DSL 的 maven {} 接收者类型是 MavenArtifactRepository，url 是一个属性，不能把字符串直接当方法参数丢进去。Groovy 里 url 'xxx' 能工作，本质上利用的是 Groovy 语法的 setter 缩写，而 Kotlin 没有这种机制。类似的差异在配置 sourceSets、任务属性时还会继续出现。

2.2 任务注册和类型化 API：Kotlin DSL 更“守规矩”

任务（Task）是 Gradle 里的核心概念。Groovy DSL 里注册一个任务很随意：

groovy复制tasks.register('hello') {
    doLast {
        println 'Hello, Gradle'
    }
}

Kotlin DSL 写起来也差不多：

kotlin复制tasks.register("hello") {
    doLast {
        println("Hello, Gradle")
    }
}

到这里差别不大。但一旦涉及具体任务类型，差距就出来了。比如你想注册一个 Copy 类型的任务，Groovy 可以这样写：

groovy复制tasks.register('copyFiles', Copy) {
    from 'src/docs'
    into 'build/docs'
}

Kotlin DSL 通常需要指定泛型类型，否则编译器不知道你正在配置的是 Copy，也就无法访问 from、into 等方法：

kotlin复制import org.gradle.api.tasks.Copy

tasks.register<Copy>("copyFiles") {
    from("src/docs")
    into("build/docs")
}

我第一次写 tasks.register("copyFiles") { ... } 时，明明在 Groovy 里没问题，换成 kts 就一直报 Unresolved reference: from。原因就是这个：register 方法返回的是 TaskProvider<Task>，如果你不写类型，编译器默认认为是通用 Task，而通用 Task 上并没有 from 方法。这种错误在 Groovy 里几乎不存在，因为 Groovy 可以在运行时动态解析任务配置闭包里的方法。

用 tasks.named 调整已有任务时也一样。Java 插件注册了 test 任务，Groovy 里你直接写：

groovy复制tasks.named('test') {
    useJUnitPlatform()
}

在 Kotlin DSL 里，useJUnitPlatform() 是 Test 任务的方法，所以你最好加上类型参数：

kotlin复制import org.gradle.api.tasks.testing.Test

tasks.named<Test>("test") {
    useJUnitPlatform()
}

如果不加 <Test>，IDE 和编译器会提示找不到 useJUnitPlatform。初学者很容易在这一步开始怀疑人生：“为什么同样的名字换了扩展名就报错？”其实不是代码错了，而是 Kotlin DSL 强制要求你把类型表达清楚。

2.3 动态属性、extra 与闭包：Groovy 很自由，Kotlin 要“走正门”

Groovy DSL 里有一种能力是 Kotlin DSL 永远做不到的：给任意扩展名动态塞属性。

groovy复制ext {
    projectName = 'demo'
}

tasks.register('printName') {
    doLast {
        println projectName
    }
}

上面这段在 Groovy 里运行得很好。但当你把同样思路搬到 .gradle.kts 中，却不能直接把 projectName 当普通属性来用，因为 Kotlin 的静态检查不允许一个不存在的属性被直接访问。你需要走 extra API：

kotlin复制extra["projectName"] = "demo"

tasks.register("printName") {
    doLast {
        println(extra["projectName"])
    }
}

读出来的时候，如果希望类型是 String，还要声明一下：

kotlin复制val projectName: String by extra

这种严格其实不是坏事。Groovy 的动态属性虽然写起来爽，但在多人协作时，你根本不知道某个属性是在哪个脚本的哪个位置注入的。Kotlin DSL 逼着你显式声明，反而让项目里不存在的魔法变量少了很多。

还有一个比较微妙的地方是闭包接收者。Groovy DSL 经常利用闭包的 delegate 让代码特别“像 DSL”，比如：

groovy复制somePlugin {
    customConfig = 'value'
}

Kotlin DSL 如果遇到一个插件没有提供完善的类型化 API，有时就要借助 withGroovyBuilder 来兼容：

kotlin复制somePlugin {
    withGroovyBuilder {
        setProperty("customConfig", "value")
    }
}

这种写法不太优雅，但它解决了一个现实问题：老插件还没适配 Kotlin DSL 时，你也能把工程迁过去。等插件版本跟上之后，再改成类型安全写法也不迟。

我整理了一张高频差异对照表，方便大家快速查阅：

3.