跳转至

21 构建工具 Gradle 入门

本章目标

  • 理解构建工具的作用
  • 掌握 Gradle 基本概念（项目结构、任务）
  • 了解 Forge MDK 工程结构
  • 学会导入并运行模组工程

21.1 为什么要学 Gradle

写模组不只是写 Java 代码，还要：

  • 下载依赖（Minecraft、Forge 的数千个类）
  • 把代码和资源打包成 jar
  • 处理 Minecraft 的反编译与混淆映射
  • 生成运行配置

这些全由 Gradle 自动化完成。Forge 的 MDK（模组开发套件）就是一套 Gradle 工程。

21.2 Gradle 核心概念

项目结构（Forge MDK 为例）

forge-1.20.1-47.x.x-mdk/
 ├── build.gradle          # 构建脚本（依赖、插件、任务配置）
 ├── settings.gradle       # 项目设置（仓库、项目名）
 ├── gradle.properties     # 版本号、Minecraft/Forge 版本配置
 ├── gradlew               # Gradle 启动脚本（Linux/Mac）
 ├── gradlew.bat           # Gradle 启动脚本（Windows）
 ├── gradle/wrapper/       # Gradle Wrapper（固定 Gradle 版本）
 ├── src/main/java/        # 模组 Java 源码
 ├── src/main/resources/   # 资源文件（mcmod.toml、语言文件、贴图、模型）
 └── run/                  # 运行游戏的工作目录（生成后）

Gradle Wrapper

不要自己装 Gradle，用项目里的 gradlew（wrapper）——它自动下载并固定版本，保证大家构建一致：

# Windows
gradlew.bat build

# Linux / macOS
./gradlew build

21.3 常用 Gradle 任务

在工程根目录运行：

# 首次准备：下载依赖、解压 Minecraft、生成运行环境
./gradlew setup

# 生成 IDEA 工程文件（导入 IDE 前跑一次）
./gradlew genSources
./gradlew idea

# 构建模组 jar（产物在 build/libs/）
./gradlew build

# 运行客户端（自动启动 Minecraft 测试模组）
./gradlew runClient

# 运行服务端
./gradlew runServer

# 清理构建缓存
./gradlew clean

IDEA 导入

用 IDEA 打开 MDK 工程的 build.gradle，选择"Open as Project"，等 Gradle 同步完即可。首次同步要下载很多东西，耐心等（可能需要十几分钟，取决于网络）。

21.4 gradle.properties（版本配置）

Forge 1.20.1 MDK 的 gradle.properties 类似：

# Minecraft 版本
minecraft_version=1.20.1
# Forge 版本（Minecraft 对应 Forge 版本号）
forge_version=47.3.0
# 模组基础信息
mod_id=ffsmod
mod_name=FFS Mod
mod_license=All Rights Reserved
mod_version=1.0.0
mod_group_id=com.ffs
mod_authors=pyz
# 映射表（混淆映射：MCP/Mojang）
mappings_channel=official
mappings_version=1.20.1

21.5 build.gradle 关键内容（了解即可）

plugins {
    id 'eclipse'
    id 'idea'
    id 'maven-publish'
    id 'net.minecraftforge.gradle' version '[6.0,6.2)'
}

// 应用 Forge 插件（核心）
apply plugin: 'net.minecraftforge.gradle'

// 仓库：Minecraft、Forge、Maven
repositories {
    maven {
        name = 'MinecraftForge'
        url = 'https://maven.minecraftforge.net/'
    }
}

// 依赖：Forge 本体
dependencies {
    minecraft "net.minecraftforge:forge:${minecraft_version}-${forge_version}"
}

// 重映射（把官方映射的类名转成运行时混淆名）
minecraft {
    mappings channel: mappings_channel, version: mappings_version
    runs {
        client { ... }
        server { ... }
    }
}

不用背

初学者不用理解 build.gradle 每一行，MDK 自带的配置改改版本号就能用。等你要加第三方模组 API 依赖时再回来学 dependencies { implementation 'xxx' } 即可。

21.6 常见问题

下载慢 / 失败

  • 换镜像仓库（阿里云 Maven 镜像）
  • 科学上网
  • 反复 ./gradlew 重试

Java 版本不对

Forge 1.20.1 需要 JDK 17。检查：

java -version   # 必须是 17.x

找不到符号 / 类路径错误

一般是依赖没同步完：./gradlew --refresh-dependencies 或重启 IDEA 重新导入。

内存不足

修改 gradle.properties：

org.gradle.jvmargs=-Xmx4G

21.7 小练习

  1. 去 Forge 官网 下载 1.20.1 的 MDK 并解压
  2. 用 IDEA 打开 build.gradle，等待依赖同步完成
  3. 跑一次 ./gradlew genSources（生成 Minecraft 源码，写代码时能看源码）
  4. 跑一次 ./gradlew runClient，确认能启动游戏（模组还没写，先验证环境）

本章小结

  • Gradle = 构建工具，自动下载依赖、打包、生成运行环境
  • 用项目自带的 gradlew，不要自己装
  • 常用任务：genSources / build / runClient / runServer
  • Forge 1.20.1 用 JDK 17
  • MDK 结构：src/main/java 写代码，src/main/resources 放资源

下一章：22 第一个 Forge 模组

🏠 返回总站