第1章 Gradle与Kotlin DSL环境搭建

1.1 原理概述

Gradle 是基于 有向无环图（DAG） 的任务编排引擎。Kotlin DSL 将 Groovy 动态脚本替换为 Kotlin 静态类型语言，使构建脚本获得编译期类型检查、IDE 自动补全和重构支持。底层原理可概括为三层结构：

1. 构建生命周期层：初始化（settings.gradle.kts）→ 配置（build.gradle.kts）→ 执行（Task 图）
2. 领域对象模型层：Project、Task、Configuration、Extension 等 API 均由 Kotlin 扩展函数和委托属性实现
3. 脚本编译层：Kotlin 编译器将 .kts 脚本预编译为抽象语法树（AST），再交由 Gradle 运行时解析

1.2 环境要求与工具版本对照

搭建前必须确认以下工具的兼容版本：

1.3 JDK配置与验证

原理：Gradle 本质是 JVM 进程，通过 JAVA_HOME 定位运行时 JDK。未配置时回退到系统 PATH 中的 java。

配置步骤（macOS/Linux）

# 查看已安装 JDK 路径
/usr/libexec/java_home -V

# 临时设置（当前终端）
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

# 持久化写入 ~/.zshrc 或 ~/.bash_profile
echo 'export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home' >> ~/.zshrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 验证
java -version

配置步骤（Windows）

# 系统变量 → 新建
变量名: JAVA_HOME
变量值: C:\Program Files\Java\jdk-21

# Path 变量追加
%JAVA_HOME%\bin

# 验证（新开 cmd）
java -version

1.4 Gradle安装与配置

Gradle 提供四种安装方式：

手动安装验证

# Linux/macOS 解压
unzip gradle-8.10-bin.zip -d /opt/gradle
export GRADLE_HOME=/opt/gradle/gradle-8.10
export PATH=$GRADLE_HOME/bin:$PATH

# Windows 解压后设置系统变量
# GRADLE_HOME = D:\tools\gradle-8.10
# Path 追加 %GRADLE_HOME%\bin

# 验证
gradle --version

预期输出（节选）

------------------------------------------------------------
Gradle 8.10
------------------------------------------------------------
Build time:   2024-12-15 12:34:56 UTC
Revision:     abcdef1234567890abcdef1234567890abcdef12
Kotlin:       2.0.21
Groovy:       3.0.21
JVM:          21.0.1 (Oracle Corporation 21.0.1+12-LTS)
OS:           Mac OS X 14.3 x86_64

1.5 IntelliJ IDEA与Kotlin DSL插件

原理：IDEA 通过 Kotlin 插件 实现 .kts 文件的语法高亮、代码补全和错误提示。Gradle 支持通过 Kotlin DSL 自动导入 将构建脚本中的类型映射到 IDE 内部。

插件配置步骤

1. 打开 IntelliJ IDEA → Settings (macOS: Cmd+, Windows: Ctrl+Alt+S)
2. 进入 Plugins → Marketplace → 搜索 Kotlin
3. 安装官方 Kotlin 插件（版本 ≥ 2.0.21）
4. 重启 IDE
5. 验证：新建文件 test.gradle.kts，输入 task 触发代码补全

1.6 第一个Kotlin DSL构建脚本验证

创建空白项目，手工编写 build.gradle.kts 并执行。

项目结构

gradle-kts-demo/
├── build.gradle.kts
├── settings.gradle.kts
└── src/
    └── main/
        └── kotlin/
            └── com/example/
                └── App.kt

settings.gradle.kts

rootProject.name = "gradle-kts-demo"

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

build.gradle.kts

plugins {
    kotlin("jvm") version "2.0.21"
    application
}

repositories {
    mavenCentral()
}

dependencies {
    implementation(kotlin("stdlib"))
}

application {
    mainClass.set("com.example.AppKt")
}

App.kt

package com.example

fun main() {
    println("Hello, Gradle Kotlin DSL!")
}

初始化并执行

# 生成 Gradle Wrapper（锁定 Gradle 版本）
gradle wrapper --gradle-version 8.10

# 清理 + 构建
./gradlew clean build

# 运行应用
./gradlew run

预期控制台输出

> Task :compileKotlin
Using Kotlin incremental compilation
> Task :run
Hello, Gradle Kotlin DSL!
BUILD SUCCESSFUL in 3s
3 actionable tasks: 3 executed

1.7 常见错误与调试

1.8 稳定性优化建议

• 固定 Gradle Wrapper 版本：使用 gradle wrapper --gradle-version 8.10 生成 gradle-wrapper.properties，确保 CI 与本地环境一致。
• 启用 Build Cache：在 gradle.properties 中设置 org.gradle.caching=true，配合 Develocity 或本地 file-based cache 提升增量构建速度。
• 调整 Daemon JVM 参数：org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m 避免大项目 OOM。
• 配置 Kotlin Daemon：在 gradle.properties 中增加 kotlin.daemon.jvmargs=-Xmx2g，独立控制 Kotlin 编译进程内存。