Opal×Terminus

如何搭建 Fabric 开发环境 (2026)

搭建Fabric模组开发环境：安装JDK，克隆示例模组模板，选择Yarn映射，然后运行gradle genSources和runClient。完整指南.

Guidesby trqUpdated June 4, 2026
Key takeaways
  • 设置包括四个步骤：JDK、示例模组模板、你的映射文件，以及 Gradle。
  • Fabric 构建插件会下载 Minecraft 并为你配置运行任务。
  • 你无需自行安装 Gradle：模板中包含一个包装器。
  • gradle.properties 文件中的版本不匹配是新项目失败的最常见原因.

搭建 Fabric 开发环境需要四个步骤：安装一个 JDK，从官方示例模组模板开始，选择你的映射（通常是 Yarn），然后运行 Gradle 任务来下载 Minecraft 并启动一个测试客户端。构建插件负责处理繁重的工作。在开始时就匹配你的 JDK 和 Minecraft 版本，其余部分就会自然而然地跟上.

Opal 的适用场景

Opal 是一个 Fabric 模组，它使用 GraalVM JavaScript 脚本引擎，因此您可以无需设置完整的模组工具链即可通过脚本对其进行扩展。 如果您只想安装并运行它，请遵循 设置指南； 要开始编写脚本，请参阅 脚本文档。

首先你需要

在编写任何代码之前，你需要三个东西：Java 开发工具包、集成开发环境 (IDE) 和 Git。

  • 一个 JDK。 确保它与你目标版本的 Minecraft 兼容。较新的 Minecraft 版本需要较新的 JDK，所以在开始之前请检查版本要求。
  • 一个 IDE。 IntelliJ IDEA 或 Eclipse 都可以使用。大多数 Fabric 开发者使用 IntelliJ，因为 Gradle 和反编译器集成更加顺畅。
  • Git。 你将克隆模板仓库并跟踪你自己的更改。

你不需要自行安装 Gradle。模板自带 Gradle 包装脚本，首次运行时会自动下载正确的版本。

逐步操作

1

安装一个 JDK

安装与你的目标 Minecraft 版本相匹配的 JDK，并将你的 IDE 指向它
2

获取模组模板示例

Fabric 发布了官方入门仓库。克隆它或将其用作模板，然后将包名和模组 ID 重命名为您的
3

选择您的映射关系

默认情况下，此模板使用 Yarn。Yarn 为 Minecraft 的类和方法提供可读且带有文档说明的名称。请在 gradle.properties 文件中设置 Minecraft 版本、加载器版本和 Yarn 映射版本
4

生成来源并运行

在你的 IDE 中打开项目，让 Gradle 同步，然后运行 genSources 以 Yarn 命名反编译 Minecraft。运行 runClient 任务来启动你的模组已加载的开发客户端

构建插件对您的帮助

Fabric 的 Gradle 构建插件会下载 Minecraft，将其重映射到您选择的映射文件，并配置运行配置。您可以通过 build.gradle 文件中的一个小区块来配置它。

您设置位置它控制
Minecraft 版本gradle.properties您编译的游戏版本
加载器版本gradle.properties您的模组运行的 Fabric 加载器版本
Yarn 版本gradle.properties您源代码中使用的映射名称
依赖项build.gradleFabric API 以及任何库

请保持 gradle.properties 中的三个版本一致。Minecraft 版本和 Yarn 映射版本不匹配是全新项目无法同步的最常见原因。

为什么映射在这里很重要

Minecraft 包含混淆代码，因此其类名类似于 a.a.a。 Yarn 将这些映射到可读名称，并位于稳定的 intermediary 层之上。 当您运行 genSources 时，构建插件使用 Yarn 名称反编译游戏，以便您可以直接读取和引用 Minecraft 代码。 当它编译您的模组时，它会将 Yarn 命名的代码重新映射回 intermediary，以便最终的 jar 文件可以在任何匹配的安装上运行，而无论映射名称如何.

项目无法构建时

  • Gradle 同步在导入后立即失败：通常，gradle.properties 文件中的 Minecraft、加载器和 Yarn 版本不匹配。请将它们设置为一组已知的匹配版本.
  • Java版本错误：当您的JDK版本低于Minecraft版本所需时，构建会报告不受支持的类文件版本。请安装更新的JDK并将其指向项目.
  • 没有可读取的编译后源代码：请运行 genSources 并重新加载。首次运行需要一些时间，因为它会编译整个游戏.
  • runClient 命令不做任何操作：请在运行任何任务之前，等待 Gradle 初始同步完成。运行配置在同步期间生成.

常见问题

获取 Opal，一个 Fabric 客户端，用于 $8.99