# 迁移 Gradle 构建脚本到 Kotlin DSL

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt).

> **TL;DR**
> 必需插件：   Gradle  （ [已安装并默认启用](managing-plugins.html#open-plugin-settings)）
>
>
>
> Gradle 版本：5.0 或更高

Kotlin DSL 是编写 Gradle 构建脚本的推荐方式。 提供类型安全的访问器，完整 IDE 代码补全与内联文档支持，并能够在编译时而非运行时捕获配置错误

本教程介绍如何把 Groovy DSL  `build.gradle`  文件转换为 Kotlin DSL  `build.gradle.kts`  文件，以及 IntelliJ IDEA 如何在补全、检查和重构方面为你提供帮助。

## 步骤 1。 重命名构建脚本

只要重命名该文件，Gradle 即可切换 DSL。 IntelliJ IDEA 会检测到更改，并立即重新索引构建。

Procedure: 将 build.gradle 重命名为 build.gradle.kts

1. 在   项目   工具窗口中，右键点击  `build.gradle`  并选择   重构 | 重命名   `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Ctrl+R` (NetBeans), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS))。

2. 将名称更改为  `build.gradle.kts` ，然后点击   重构  。

IntelliJ IDEA 会重命名文件并触发 Gradle 同步   Gradle   工具窗口会显示同步进度。

> **Note:**
> 如果项目中有  `settings.gradle`  文件，也要将其重命名为  `settings.gradle.kts` 。 支持混合 Groovy/Kotlin DSL，但完全使用 Kotlin DSL 更易维护。

同步项目。 同步完成后，检查需修正的语法。

## 步骤 2。 更新脚本语法

Kotlin DSL 使用 Kotlin 语法，因此需要更新部分构造 最常见的更改如下所示。 打开文件后，IntelliJ IDEA 会在编辑器中提供完整 Kotlin 代码补全和内联文档支持——在任何符号上按 `Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Ctrl+Q` (NetBeans), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS)) 可查看文档

### 字符串和方法调用

将单引号的 Groovy 字符串替换为双引号的 Kotlin 字符串，并为在 Groovy 中缺少圆括号的方法调用添加圆括号

> **Note:**
> 也请不要忘记更改  `plugins`  部分的语法。

Groovy DSL:

```GROOVY
group = 'org.example'
version = '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:5.11.0'
}

```

Kotlin DSL:

```KOTLIN
group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.0")
}

```

也不要忘记更改 Groovy 列表文字  `[]`  请查看以下示例：

Groovy DSL:
`applicationDefaultJvmArgs = ["-Dfile.encoding=UTF-8"]`

Kotlin DSL:
`applicationDefaultJvmArgs = listOf ("-Dfile.encoding=UTF-8")`

此外请注意，Kotlin 中没有动态扩展程序 因此，如果在  `build.gradle`  中有  `ext`  块，请参考下方 Kotlin DSL 语法示例。

Groovy DSL:

```GROOVY
ext {
    junitVersion = "5.10.2"
    guavaVersion = "33.0.0-jre"
}


```

Kotlin DSL:

```KOTLIN
val junitVersion = "5.10.2"
val guavaVersion = "33.0.0-jre"
```

如果有使用 Groovy map 语法 (  `"key": value` ) 的  `attributes`  块，也需要更改语法，因为 Kotlin 构建 map 用的是  `mapOf(...)`  和  `为`  对而不是冒号。 请查看以下示例：

Groovy DSL:

```GROOVY
attributes(
        "Implementation-Title": project.name,
        "Implementation-Version": project.version,
        "Main-Class": "com.example.app.App"
)


```

Kotlin DSL:

```KOTLIN
attributes(mapOf(
    "Implementation-Title" to project.name,
    "Implementation-Version" to project.version,
    "Main-Class" to "com.example.app.App"
))

```

### 任务配置

在 Kotlin DSL 中，任务配置使用类型安全访问器。 请使用  `tasks.test`  替代动态  `test`  简写。

Groovy DSL:

```GROOVY
test {
    useJUnitPlatform()
}

```

Kotlin DSL:

```KOTLIN
tasks.test {
    useJUnitPlatform()
}

```

> **Tip:**
> 开始输入  `tasks.`  并按 `Ctrl+Space` (Windows), `⌃ Space` (macOS), `⌃ Space` (IntelliJ IDEA Classic (macOS)), `⌃ Space` (macOS System Shortcuts), `Ctrl+Space` (XWin), `Ctrl+Space` (GNOME), `Ctrl+Space` (KDE), `Alt+/` (Emacs), `Ctrl+Space` (Sublime Text), `⌃ Space` (Sublime Text (macOS)), `Ctrl+Space` (Visual Studio), `⌃ Space` (Visual Studio (macOS)), `Ctrl+Space` (NetBeans), `Ctrl+Space` (Eclipse), `⌃ Space` (Eclipse (macOS))，即可看到针对已应用插件的所有类型安全任务访问器。

## 步骤 3。 迁移到 plugins 块

若构建脚本使用了旧版  `apply plugin:`  语法，IntelliJ IDEA 会用   使用“plugins”块替代“apply plugin”标签。   检查高亮显示 迁移到  `plugins {}`  块后，可为插件的扩展程序与任务启用类型安全访问器。

Procedure: 用 plugins 块替换 apply plugin

1. 在编辑器中打开  `build.gradle.kts` 。

脚本采用  `apply(plugin = "...")`  应用插件时，IntelliJ IDEA 会对该调用加下划线并弹出警告。

```KOTLIN
apply(plugin = "java")       // highlighted by inspection
apply(plugin = "application")

```

2. 将文本光标置于高亮显示的调用上并按 `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)) 以打开意图列表 选择   使用 'plugins' 块  。

IntelliJ IDEA 会将所有  `apply(plugin = ...)`  调用替换为文件顶部的单一  `plugins {}`  块。

```KOTLIN
plugins {
    java
    application
}

```

但如果你使用了第三方插件，则请采用以下语法：

```KOTLIN
plugins {
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

```

3. [同步 Gradle 项目](work-with-gradle-projects.html#gradle_refresh_project)以应用更改。

同步完成后，与插件（如  `application { ... }` ）相关的类型安全访问器将支持完整补全。

## 步骤 4。 移除冗余的 Kotlin 标准库依赖项

使用 Kotlin Gradle 插件时，会自动将 Kotlin 标准库加为依赖项。 如果构建脚本同时显式声明该依赖项，IntelliJ IDEA 会用   冗余的 Kotlin 标准库依赖项   检查高亮显示冗余条目

Procedure: 移除冗余的 stdlib 依赖项

1. 打开  `build.gradle.kts` 。

若已应用  `kotlin("jvm")`  插件，又显式声明了  `stdlib` ，IntelliJ IDEA 会把该依赖标记为冗余：

```KOTLIN
plugins {
    kotlin("jvm") version "2.1.0"
}

dependencies {
    implementation(kotlin("stdlib"))  // highlighted as redundant
}

```

2. 将文本光标放在高亮显示的依赖上并按 `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)) 选择   移除冗余依赖项  。

IntelliJ IDEA 会移除显式  `stdlib`  声明。 该依赖依然通过 Kotlin 插件包含在类路径上。

> **Note:**
> 在  `build.gradls.kts`  中生成依赖非常容易，只需开始输入依赖作用域或名称，代码补全建议即会显示

## 步骤 5。 重命名构建文件中的符号

IntelliJ IDEA 将 Gradle 构建文件视为一等 Kotlin 源文件。   重命名   重构不仅适用于  `build.gradle.kts` 、  `settings.gradle.kts` ，在同一项目中的任何  `buildSrc`  文件也同样适用。

Procedure: 重命名构建文件中使用的符号

1. 将文本光标放在需要重命名的符号上——例如在  `buildSrc`  声明、在  `build.gradle.kts`  引用的属性。

2. 按 `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Ctrl+R` (NetBeans), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS)) 打开   重命名   对话框。

3. 输入新名称并点击   重构  。

IntelliJ IDEA 会自动更新所有构建文件中的引用。

## 下一步

迁移到 Kotlin DSL 后，还可以探索更多 Gradle 项目的 IDE 功能：

* [运行与管理 Gradle 任务](work-with-gradle-tasks.html)

* [可视化项目依赖关系](work-with-gradle-dependency-diagram.html)

* [在 IntelliJ IDEA 中 Gradle 入门](getting-started-with-gradle.html)