用 Java 开发你的第一个 Fabric 模组

Mission 01 · 学完能做什么

不是“照着敲完”，而是建立一张能继续成长的开发地图。

很多初学教程一上来就复制几十行注册代码，学生虽然看见游戏里多了东西，却不知道 JDK、Gradle、Fabric Loader 和 Fabric API 各自负责什么。一旦版本不同、包名改了或依赖下载失败，就完全不知道从哪里检查。本课先建立模型，再完成一个小而完整的作品。你会知道每个文件为何存在、每条命令在哪一层运行，以及错误信息应该从哪一行开始读。

Version strategy · 先把版本固定住

模组开发最怕的不是代码难，而是把不同年代的教程拼在一起。

Fabric、Minecraft、Java、Loader、Loom 和 Fabric API 都有自己的版本。网络上 1.20.1、1.21.1、1.21.11 与 26.x 的类名和资源格式可能不同。看见“最新版本”就全部升级，往往会让一份本来正确的示例无法编译。为了让学生稳定复现，本课锁定 Minecraft Java 1.21.1 与 JDK 21，并使用 Fabric 官方示例工程当前为 1.21.1 分支给出的依赖组合。

开始之前请准备

• 一台可以运行 Minecraft Java Edition 的 Windows 电脑，以及你有权使用的正版游戏账号。
• 至少 8 GB 内存；第一次 Gradle 同步需要联网下载依赖，速度取决于网络。
• JDK 21。注意 JRE 只能“运行”，JDK 才包含 javac 等开发工具。
• IntelliJ IDEA Community Edition。它足够完成 Fabric Java 开发，不需要购买 Ultimate。
• 一个纯英文、无空格、非 OneDrive 的工程路径，例如 C:\Projects\teacherma-fabric-intro。

Mental model · Fabric 到底是什么

它不是一个“做模组按钮”，而是一条可组合的 Java 工具链。

Fabric Loader 是加载器：启动游戏时读取每个模组的 fabric.mod.json，检查 ID、依赖和入口类，再调用你的代码。Fabric API 是常用开发接口集合：提供命令注册、事件、物品组、网络通信等更稳定的接入点。Fabric Loom 是 Gradle 插件：帮你下载游戏与映射、生成运行配置、启动开发客户端、重映射并构建 JAR。IntelliJ IDEA 则是你写代码和调试的工作台。

Setup · 安装与创建工程

先验证工具，再生成模板；不要在空文件夹里凭记忆手写 Gradle 配置。

1

确认 JDK 21，而不是只确认“装过 Java”

打开 PowerShell，分别运行下面两条命令。第一条检查运行环境，第二条检查编译器。两者都应该显示 21。如果 javac 不存在，通常说明只装了 JRE，或系统 PATH 没有指向 JDK。

PowerShell复制

java -version
javac -version

2

让 IntelliJ 的 Project SDK 与 Gradle JVM 都使用 JDK 21

进入 File → Project Structure → Project，把 SDK 设为 21；再进入 Settings → Build, Execution, Deployment → Build Tools → Gradle，把 Gradle JVM 也设为同一个 JDK 21。只改其中一处，仍可能出现“编辑器看起来正常，但构建失败”的情况。

3

从 Fabric Template Mod Generator 生成工程

打开官方生成器，填写：Mod Name 为 TeacherMa Fabric Intro，Mod ID 为 teacherma_fabric_intro，Package Name 为 dev.teacherma.fabricintro，Minecraft Version 选择 1.21.1，语言保持 Java。本课建议保留“拆分 client 与 main 源集”，它能更早发现把客户端类写到服务端代码里的错误。

打开 Fabric 官方生成器

4

解压到简单路径，并在 IntelliJ 中打开“工程根目录”

推荐路径是 C:\Projects\teacherma-fabric-intro。选择 File → Open 后，应打开包含 build.gradle、gradlew.bat 和 src 的那一层文件夹，不要只打开 src。看到 Gradle 构建脚本提示时选择导入，并等待索引和依赖下载结束。

5

用课程 Starter 工程快速对照

如果你想先跑通再逐项比较，可以下载本课已经验证过的工程。它保留官方 Gradle Wrapper 和版本组合，并加入最终的命令代码。把它放在独立文件夹中打开，不要覆盖你自己的练习工程。

TeacherMa Fabric Intro Starter

包含完整源码、Gradle Wrapper、版本配置和中文 README。下载接口受课程权限保护。

下载 ZIP

Project map · 看懂工程结构

能说出这些文件的职责，才算真正“打开了项目”。

teacherma-fabric-intro/
├─ gradle/                         # Gradle Wrapper 运行文件
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │  └─ dev/teacherma/fabricintro/
│  │  │     └─ FabricIntroMod.java # 通用/服务端入口逻辑
│  │  └─ resources/
│  │     └─ fabric.mod.json         # 模组说明书
│  └─ client/                       # 仅客户端代码与资源
├─ build.gradle                     # 插件、依赖与构建规则
├─ gradle.properties                # Minecraft/Fabric 版本
├─ settings.gradle                  # 工程名称与插件仓库
└─ gradlew.bat                      # Windows 下执行 Gradle

fabric.mod.json：Loader 先读的模组说明书

这里的 id 是整个模组的命名空间，必须使用小写字母、数字和下划线等安全字符；它也会出现在物品 ID、资源路径和日志中。entrypoints.main 必须与 Java 类的完整包名完全一致，任何一个字母不一致都会导致入口类找不到。depends 则声明最低 Loader 版本、目标 Minecraft、Java 和 Fabric API。

{
  "schemaVersion": 1,
  "id": "teacherma_fabric_intro",
  "name": "TeacherMa Fabric Intro",
  "environment": "*",
  "entrypoints": {
    "main": ["dev.teacherma.fabricintro.FabricIntroMod"]
  },
  "depends": {
    "fabricloader": ">=0.19.3",
    "minecraft": "~1.21.1",
    "java": ">=21",
    "fabric-api": "*"
  }
}

gradle.properties：版本要成套出现

版本不是越新越好，而是要彼此兼容。Minecraft 版本决定你面对哪一套游戏代码；Loader 负责加载；Fabric API 必须带有适配目标游戏的后缀。Loom 版本由同一模板生成器给出。升级时不要只把 minecraft_version 改成新数字，然后期待所有依赖自动兼容。

Code · 编写第一个可见功能

注册一个命令，让 Java 代码在服务端真正改变玩家状态。

我们选择命令作为第一项功能，因为它同时展示入口生命周期、Fabric API 事件、命令树、执行上下文、服务端玩家对象和游戏物品对象，又不需要先处理贴图、模型与语言文件。输入 /hello_fabric 后，命令在逻辑服务端执行，向当前玩家物品栏加入一颗绿宝石，并发送一条成功消息。

package dev.teacherma.fabricintro;

import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.command.v2.CommandRegistrationCallback;
import net.minecraft.commands.Commands;
import net.minecraft.network.chat.Component;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.Items;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class FabricIntroMod implements ModInitializer {
    public static final String MOD_ID = "teacherma_fabric_intro";
    public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

    @Override
    public void onInitialize() {
        CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) ->
                dispatcher.register(Commands.literal("hello_fabric")
                        .executes(context -> {
                            var player = context.getSource().getPlayerOrException();
                            player.addItem(new ItemStack(Items.EMERALD));
                            context.getSource().sendSuccess(
                                    () -> Component.literal("Hello Fabric! Java 已经改变了游戏世界。"),
                                    false
                            );
                            return 1;
                        }))
        );

        LOGGER.info("TeacherMa Fabric Intro loaded successfully.");
    }
}

Run & verify · 运行与验收

第一次启动慢是正常的；“能进游戏”之后还要做四项验证。

在 IntelliJ 右侧打开 Gradle 工具窗口，找到 Fabric 相关运行任务并执行 runClient。也可以在工程根目录打开 PowerShell，使用 Wrapper 启动。Wrapper 会确保项目使用规定的 Gradle 版本，不要求学生全局安装 Gradle。

./gradlew.bat runClient

Debug clinic · 常见错误

先判断错误发生在哪一层，再决定该改设置、依赖还是 Java。

用 IntelliJ 断点观察命令执行

点击 var player = ... 左侧行号添加红色断点，然后以 Debug 模式启动客户端。进入世界执行命令时，程序会暂停。此时在 Variables 窗口查看 context、player 与玩家物品栏。按 F8 单步执行，你会亲眼看到“取得玩家 → 添加物品 → 发送消息 → 返回 1”的顺序。这比背 API 更能建立程序执行模型。

Build & install · 构建并安装

开发环境里能运行，最后还要变成普通启动器可以加载的 JAR。

关闭开发客户端，在工程根目录执行构建。Gradle 会编译 Java、处理资源、重映射名称并生成可发布文件。构建成功后打开 build/libs，选择文件名最短、且不包含 sources 的 JAR；sources 包是给开发者阅读源码用的，不是普通玩家安装包。

./gradlew.bat clean build

Practice · 练习与自测

把“看懂”变成“能独立改动”：完成三个难度递增的小任务。

五分钟自测

术语卡