Gradle 基础

Gradle 是 EnderRealm 项目使用的构建工具，这个章节将介绍 Gradle 的基本概念。

什么是构建工具？

构建工具是自动化编译、打包、测试的工具。它可以帮助你：

• 编译代码：将源代码编译成可执行文件
• 管理依赖：自动下载和管理第三方库
• 运行测试：自动化测试代码
• 打包发布：生成可发布的包

为什么选择 Gradle？

Gradle 是 Java 生态中最流行的构建工具，具有以下优点：

• 灵活：支持多种语言和平台
• 高性能：增量构建、构建缓存
• 可扩展：丰富的插件生态
• 现代：支持 Kotlin DSL

Gradle 的核心概念

项目（Project）

项目是 Gradle 构建的基本单元。EnderRealm 是一个多项目构建，包含多个子项目：

EnderRealmServerCore/          # 根项目
├── EnderRealmServerCore/      # 子项目：核心插件
├── bedwars/                   # 子项目：空岛战争
├── disaster/                  # 子项目：灾难生存
├── BlockedInCombat/           # 子项目：方块战斗
├── easy4form/                 # 子项目：表单库
└── libs/EnderRealmFastGUI/   # 子项目：GUI 库

任务（Task）

任务是 Gradle 构建的基本单位。常用任务：

任务	说明
build	构建项目
clean	清理构建输出
test	运行测试
jar	生成 JAR 文件
shadowJar	生成 Fat JAR

依赖（Dependency）

依赖是项目需要的第三方库。在 build.gradle.kts 中声明：

dependencies {
    // 编译时依赖（不包含在最终 JAR 中）
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")

    // 实现依赖（包含在最终 JAR 中）
    implementation("project(:EnderRealmFastGUI)")
}

插件（Plugin）

插件扩展 Gradle 的功能。常用插件：

插件	说明
java	Java 语言支持
application	应用程序支持
shadow	Fat JAR 支持

Gradle Wrapper

Gradle Wrapper 是 Gradle 的包装器，确保团队使用相同版本的 Gradle。

文件结构

EnderRealmServerCore/
├── gradlew              # Unix 脚本
├── gradlew.bat          # Windows 脚本
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.jar      # Wrapper JAR
        └── gradle-wrapper.properties  # Wrapper 配置

使用 Wrapper

# Unix/macOS
./gradlew build

# Windows
.\gradlew.bat build

Wrapper 配置

gradle-wrapper.properties 文件：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

build.gradle.kts 文件

build.gradle.kts 是 Gradle 的构建脚本，使用 Kotlin DSL。

根项目配置

// 根项目配置
allprojects {
    // 仓库配置
    repositories {
        mavenCentral()
        maven("https://repo.papermc.io/repository/maven-public/")
    }

    // 组配置
    group = "cn.enderrealm"
    version = "1.0-SNAPSHOT"
}

子项目配置

// 子项目配置
plugins {
    id("mc-plugin-convention")  // 自定义约定插件
}

dependencies {
    // Paper API
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")

    // 核心插件
    compileOnly(project(":EnderRealmServerCore"))

    // 其他依赖
    implementation(project(":EnderRealmFastGUI"))
}

settings.gradle.kts 文件

settings.gradle.kts 定义项目结构：

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven("https://repo.papermc.io/repository/maven-public/")
    }
}

rootProject.name = "EnderRealmServerCore"

// 包含子项目
include("EnderRealmServerCore")
include("bedwars")
include("disaster")
include("BlockedInCombat")
include("easy4form")
include("EnderRealmFastGUI")

buildSrc 目录

buildSrc 目录包含自定义的构建逻辑：

buildSrc/
├── build.gradle.kts
└── src/main/kotlin/
    └── mc-plugin-convention.gradle.kts

约定插件

mc-plugin-convention.gradle.kts 定义共享的构建配置：

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

java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
}

tasks.build {
    dependsOn(tasks.shadowJar)
}

常用 Gradle 命令

构建命令

# 构建整个项目
./gradlew build

# 构建特定模块
./gradlew :bedwars:build

# 清理构建输出
./gradlew clean

# 清理并重新构建
./gradlew clean build

依赖命令

# 查看依赖树
./gradlew dependencies

# 查看特定模块的依赖
./gradlew :bedwars:dependencies

任务命令

# 查看所有可用任务
./gradlew tasks

# 查看特定组的任务
./gradlew tasks --group=EnderRealm

常见问题

Q: 构建失败怎么办？

A: 检查以下几点：

1. JDK 版本是否正确（需要 JDK 21）
2. 网络是否正常（需要下载依赖）
3. 查看错误信息，定位问题

Q: 如何加速构建？

A: 可以尝试：

1. 使用构建缓存：--build-cache
2. 并行构建：--parallel
3. 使用守护进程：--daemon

Q: 如何查看详细日志？

A: 使用以下参数：

# 信息级别
./gradlew build --info

# 调试级别
./gradlew build --debug

# 堆栈跟踪
./gradlew build --stacktrace

推荐学习资源

• Gradle 官方文档
• Gradle 教程
• Gradle Kotlin DSL

下一步

Gradle 基础了解完成后，让我们继续学习 构建项目。