第4周详细教程

搭建 Fabric 基础模板并运行首个 MOD 工程

本周目标是完成 Fabric Java 开发环境搭建、导入基础模板工程、执行构建命令，并在 Minecraft 中成功运行第一个可加载 MOD。该过程是后续功能开发的标准起点。

本章内容覆盖准备条件、目录结构、关键配置文件、运行流程与常见错误排查，形成可复用的项目初始化流程。

4.1 环境与工具准备

Fabric 开发使用 Java 技术栈，推荐基于 JDK 17 与 IntelliJ IDEA 构建开发环境。Fabric Loader 与 Fabric API 负责 MOD 运行时加载与接口支持，Gradle 负责依赖解析与工程构建。

必备组件

JDK 17（或课程指定版本）
IntelliJ IDEA（Community 或 Ultimate）
Fabric 示例模板工程（基于 Gradle）
Minecraft 对应版本客户端

版本一致性要求

`Minecraft 版本`、`Fabric Loader 版本`、`Fabric API 版本` 与 `Mappings 版本` 必须在模板中相互兼容。任意一个版本不匹配都可能导致启动失败或编译错误。

4.2 创建与导入 Fabric 基础模板

安装 JDK 17

确认终端 `java -version` 输出正确版本，作为 Fabric 构建基础。

准备模板目录

创建英文路径工程目录，放置模板文件并检查 Gradle 配置存在。

IDEA 导入工程

使用 `Open` 打开项目根目录，等待依赖同步完成。

核对版本参数

在 `gradle.properties` 对齐 Minecraft、Loader、Fabric API 版本。

运行构建命令

执行 `gradlew build` 与 `gradlew runClient` 生成并启动开发环境。

验证 MOD 加载

检查 Mods 列表与日志输出，确认首个 MOD 已成功初始化。

4.2.1 获取模板工程

使用课程提供的 Fabric 模板压缩包，或基于 Fabric 示例仓库创建项目。
将项目放入英文路径目录，避免中文路径造成构建工具解析异常。
确认项目根目录包含 `build.gradle`、`settings.gradle`、`gradle.properties`。

4.2.2 导入 IDE

在 IDEA 中选择 `Open` 打开模板根目录。
等待 Gradle 首次同步完成。
确认 `External Libraries` 中已加载 Fabric 与 Minecraft 依赖。

4.2.3 项目目录识别

路径	作用
`src/main/java`	Java 源代码目录
`src/main/resources`	资源与配置文件目录
`fabric.mod.json`	MOD 元数据与入口配置
`build.gradle`	依赖、插件、构建任务配置

4.3 关键配置文件说明

4.3.1 `gradle.properties`

用于集中管理 Minecraft、Loader、Fabric API、Mappings 等版本参数。

minecraft_version=1.20.1
yarn_mappings=1.20.1+build.10
loader_version=0.15.11
fabric_version=0.92.2+1.20.1

4.3.2 `fabric.mod.json`

用于定义 MOD 基础信息、入口类、依赖要求。

{
  "schemaVersion": 1,
  "id": "teacherma_demo",
  "version": "1.0.0",
  "name": "TeacherMa Demo Mod",
  "entrypoints": {
    "main": ["com.teacherma.demo.TeachermaDemoMod"]
  },
  "depends": {
    "fabricloader": ">=0.15.0",
    "fabric": "*",
    "minecraft": "1.20.1",
    "java": ">=17"
  }
}

4.3.3 首个入口类

package com.teacherma.demo;

import net.fabricmc.api.ModInitializer;

public class TeachermaDemoMod implements ModInitializer {
    @Override
    public void onInitialize() {
        System.out.println("TeacherMa Demo Mod 已成功加载");
    }
}

4.4 运行首个 MOD 工程

4.4.1 命令行构建

# Windows
.\gradlew.bat build

# 运行开发客户端
.\gradlew.bat runClient

首次执行时会下载依赖，时间较长属于正常现象。完成后应看到构建成功信息，并可启动带 Fabric 的开发客户端。

4.4.2 成功判定标准

Gradle 控制台出现 `BUILD SUCCESSFUL`。
Minecraft 启动后 `Mods` 列表可见当前 MOD 名称。
日志中出现入口类 `onInitialize()` 输出信息。

4.4.3 常见启动失败原因

JDK 版本错误：需确认 IDEA 与 Gradle 均使用 JDK 17。
版本不兼容：`minecraft_version` 与 `fabric_version` 不匹配。
包名与入口类路径错误：`fabric.mod.json` 与 Java 实际路径不一致。
缓存异常：依赖下载中断导致构建失败。

4.5 常见排查流程

先看首个报错，而不是只看最后一行异常信息。
核对 `gradle.properties` 版本参数是否与项目模板一致。
核对入口类包路径与 `fabric.mod.json` 的 `entrypoints` 字段。
执行 `gradlew --refresh-dependencies` 重新拉取依赖。
删除 `.gradle` 缓存后重新同步工程（必要时）。

.\gradlew.bat --refresh-dependencies
.\gradlew.bat clean build

4.6 本周成果与下一步

完成 Fabric Java 工程初始化。
掌握模板结构与核心配置文件定位。
成功运行首个可加载 MOD。
建立标准化的项目启动与排错流程。

完成本周后即可进入下一阶段功能开发，包括自定义物品、方块交互与事件逻辑扩展。

返回第一阶段