如何搭建 Fabric 开发环境

搭建 Fabric 模组开发环境需要四个步骤：安装 Java 开发工具包，从官方示例模组模板开始，配置 Yarn 映射，然后运行 Gradle。Fabric 构建插件会下载 Minecraft 并连接所有其他组件。在开始时就匹配你的 JDK 和 Minecraft 版本，构建系统会处理剩下的事情。

你首先需要什么

在编写代码之前：

• 一个与你的 Minecraft 版本匹配的 JDK。 新版本的 Minecraft 需要更新的 JDK。在安装之前，请检查目标版本的要求。
• 一个集成开发环境 (IDE)。 IntelliJ IDEA Community (免费) 或 Eclipse 都可以很好地工作。大多数 Fabric 开发者使用 IntelliJ，因为 Gradle 集成更加顺畅。
• Git。 你将克隆模板仓库并管理你自己的代码。

你不需要安装 Gradle。模板包含一个包装脚本，该脚本会在首次运行时下载正确的版本。

步骤分解

1. 安装一个 JDK

   下载与您目标 Minecraft 版本相符的 Adoptium 或 Oracle JDK。对于 Minecraft 1.21，请安装 Java 21。在 IDE 的设置中指向此 JDK.

2. 获取模组模板示例

   前往 Fabric 官方示例模组仓库，克隆它或将其用作模板。将包名和模组 ID 重命名为您的专属名称.

3. 在 gradle.properties 中设置版本

   打开 gradle.properties 文件，更新以下三行：

   • minecraft_version — 您的目标 Minecraft 版本（例如，1.21）
   • loader_version — 与您的 Minecraft 构建匹配的 Fabric 载入器版本
   • yarn_mappings — 适用于您的 Minecraft 版本的 Yarn 版本

   这三者必须一致，否则项目将无法构建.

4. 在你的 IDE 中打开并同步

   在你的 IDE 中打开项目文件夹。让 Gradle 执行一次初始同步（下载依赖项，生成运行配置）.

5. 生成反编译源代码

   在你的 IDE 的 Gradle 面板中，运行 genSources。 这会使用 Yarn 命名来反编译 Minecraft，以便你可以阅读游戏的源代码.

6. 启动测试客户端

   运行 runClient 以加载你的模组并启动 Minecraft。开发客户端包含完整的调试功能.

就是这样。你现在拥有了一个可用的Fabric开发环境

理解 gradle.properties

此文件配置您的整个构建。三个版本必须保持同步：

minecraft_version=1.21
loader_version=0.15.11
yarn_mappings=1.21+build.32

如果Minecraft是 1.21 但 Yarn 是 1.20.1，Gradle 同步将失败并显示一个神秘的错误。始终从 fabricmc.net/use 或示例模板获取匹配的版本

构建插件的作用

Fabric Gradle 插件在 build.gradle 文件中进行配置，并负责：

• 下载 Minecraft
• 使用您选择的映射进行反编译
• 将您的代码重新映射回中间格式以实现兼容性
• 生成 IDE 运行配置

您只需配置一次，它就能自动完成其余操作。这就是模板重要的原因——它已经正确地配置好了所有这些

映射详解

Minecraft 发布的代码经过混淆（类名如 a、b、c）。映射文件可以将这些混淆的名称转换为可读的名称。

• Yarn: Fabric 的默认映射。包含文档。易于阅读。
• Mojang 映射: 官方的，但文档较少。名称更晦涩。

模板使用 Yarn。当你运行 genSources 时，Minecraft 会使用 Yarn 名称进行反编译，以便你可以阅读实际的代码。在编译时，Fabric 会将其重新映射回中间层（一个稳定的底层），以便模组可以在任何匹配的 Minecraft 版本上运行

常见设置问题

• ✓Gradle 同步立即失败：请检查 gradle.properties 文件。Minecraft、加载器和 Yarn 版本必须匹配。请使用 Fabric 网站上已知的组合。
• ✓编译器关于 Java 版本的错误：您的 JDK 版本过旧，不兼容 Minecraft 版本。请安装更新的 JDK 并将其指向您的 IDE。
• ✓无法阅读 Minecraft 源代码：在 Gradle 面板中运行 genSources 并重新加载。首次运行较慢，因为它会反编译整个游戏。
• ✓runClient 操作不做任何事情：等待 Gradle 初始同步完成。运行配置在同步期间生成。
• ✓IDE 无法导入项目：请确保 IDE 的设置中选择了 JDK，而不是 JRE。

设置后的后续步骤

一旦您的环境正常运行：

1. 删除或重命名示例模组类
2. 创建您自己的模组包
3. 实现一个简单的功能（一个方块、物品或事件监听器）
4. 运行 runClient 并于开发客户端中进行测试
5. 迭代

开发客户端包含完整的调试和热重载支持，使迭代速度更快。

IDE 相关的说明

IntelliJ IDEA:

• 导入为 Gradle 项目（而不是仅仅是一个文件夹）
• 在运行任何任务之前，让 Gradle 完全同步
• 运行配置出现在运行下拉菜单中的“Gradle”下

Eclipse:

• 导入为现有的 Gradle 项目
• 右键单击项目 → Gradle → 在同步后刷新 Gradle 项目
• Gradle 任务出现在 Gradle 任务视图中

常见问题解答