迁移 Gradle 构建脚本到 Kotlin DSL

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

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

步骤 1。重命名构建脚本

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

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

在项目工具窗口中，右键点击 build.gradle 并选择重构 | 重命名 Shift+F6。
将名称更改为 build.gradle.kts ，然后点击重构。
IntelliJ IDEA 会重命名文件并触发 Gradle 同步 Gradle 工具窗口会显示同步进度。

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

步骤 2。更新脚本语法

Kotlin DSL 使用 Kotlin 语法，因此需要更新部分构造最常见的更改如下所示。打开文件后，IntelliJ IDEA 会在编辑器中提供完整 Kotlin 代码补全和内联文档支持——在任何符号上按 Ctrl+Q 可查看文档

字符串和方法调用

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

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

                        repositories {
                            mavenCentral()
                        }

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

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

                        repositories {
                            mavenCentral()
                        }

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

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

applicationDefaultJvmArgs = ["-Dfile.encoding=UTF-8"]

applicationDefaultJvmArgs = listOf ("-Dfile.encoding=UTF-8")

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

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

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

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

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

                    
     

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

任务配置

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

                        test {
                            useJUnitPlatform()
                        }
                    
     

                        tasks.test {
                            useJUnitPlatform()
                        }
                    
     

步骤 3。迁移到 plugins 块

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

用 plugins 块替换 apply plugin

在编辑器中打开 build.gradle.kts 。
脚本采用 apply(plugin = "...") 应用插件时，IntelliJ IDEA 会对该调用加下划线并弹出警告。
apply(plugin = "java") // highlighted by inspection apply(plugin = "application")
将文本光标置于高亮显示的调用上并按 Alt+Enter 以打开意图列表选择使用 'plugins' 块。
IntelliJ IDEA 会将所有 apply(plugin = ...) 调用替换为文件顶部的单一 plugins {} 块。
plugins { java application }
但如果你使用了第三方插件，则请采用以下语法：
plugins { id("com.github.johnrengelman.shadow") version "8.1.1" }
同步 Gradle 项目以应用更改。
同步完成后，与插件（如 application { ... } ）相关的类型安全访问器将支持完整补全。

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

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

移除冗余的 stdlib 依赖项

打开 build.gradle.kts 。
若已应用 kotlin("jvm") 插件，又显式声明了 stdlib ，IntelliJ IDEA 会把该依赖标记为冗余：
plugins { kotlin("jvm") version "2.1.0" } dependencies { implementation(kotlin("stdlib")) // highlighted as redundant }
将文本光标放在高亮显示的依赖上并按 Alt+Enter 选择移除冗余依赖项。
IntelliJ IDEA 会移除显式 stdlib 声明。该依赖依然通过 Kotlin 插件包含在类路径上。

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

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

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

将文本光标放在需要重命名的符号上——例如在 buildSrc 声明、在 build.gradle.kts 引用的属性。
按 Shift+F6 打开重命名对话框。
输入新名称并点击重构。
IntelliJ IDEA 会自动更新所有构建文件中的引用。

下一步

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

2026年 7月 14日