简介本资源是适用于Minecraft 1.20.1版本的Forge模组开发工具包MDK面向Java初学者、Minecraft模组开发者及开源爱好者解决从零搭建稳定开发环境、快速上手模组编译与调试的核心需求。压缩包共17个文件涵盖4个关键文本文件changelog.txt记录版本变更、LICENSE.txt明确开源协议、CREDITS.txt致谢贡献者、README.txt提供基础指引、2个Gradle配置文件build.gradle定义构建逻辑、settings.gradle管理项目结构、2个系统脚本gradlew.bat与gradlew支持跨平台构建、2个properties配置gradle.properties优化构建参数、gradle-wrapper.properties控制包装器行为以及jar、toml、gitignore等辅助文件整体仅111KB轻量易部署。已有1483人学习下载资源结构完整、开箱即用包含标准src目录、resources资源路径、gradle wrapper封装及MC元数据文件mcmeta可直接导入IDE进行模组开发、调试与打包是入门Forge生态与实践JavaMinecraft协同开发的理想起点。1. Forge-1.20.1不是Mod开发入门课而是你第一次真正把Java代码编译进Minecraft运行时的临界点如果你刚在IDE里敲完System.out.println(Hello, Forge!)却卡在gradlew build报错Could not resolve net.minecraftforge:forge:1.20.1-47.1.0或者反复刷新Maven仓库却始终拉不到1.20.1对应的mapped或universaljar——恭喜你已经站在Forge生态最真实的门槛上。Forge-1.20.1不是单纯升级版本号它是Mojang首次强制启用--enable-previewJVM参数、Gradle 8.2深度绑定、以及loom插件接管整个构建生命周期后的第一个稳定大版本。这意味着旧版build.gradle里手写的minecraft块会直接失效Mod注解必须配合IEventBus显式注册连resources/assets/mymod/lang/en_us.json的路径校验都从“存在即加载”变成“CRC32校验失败则静默跳过”。它适合两类人一是已用过1.16.5/1.18.2但想迁移到现代工具链的Mod作者二是Java基础扎实、愿意直面Gradle黑匣子而非依赖GUI一键生成器的新手。本文不讲“如何创建第一个方块”只解决“为什么你的1.20.1项目死活跑不起来”这个具体问题。2. 用官方Gradle脚本在本地跑通Forge-1.20.1的最小命令绕过GitHub模板陷阱的三步法Forge-1.20.1的初始化早已脱离forgegradle时代官方唯一可信入口是 https://github.com/MinecraftForge/ForgeGradle 仓库的v5分支注意不是master。但直接克隆该仓库会得到一个空壳——因为真正的初始化逻辑藏在ForgeGradle的init子命令里。常见错误是去第三方网站下载所谓“1.20.1模板zip”结果里面混着过期的fg.deobf配置或错误的mappings channel。下面是最小可行路径全程离线可复现2.1 创建纯净项目目录并初始化Gradle Wrapper先确保系统已安装JDK 17必须是JDK 17.0.1OpenJDK或Liberica均可但JDK 21会触发--enable-preview冲突mkdir mymod-1201 cd mymod-1201 curl -s https://raw.githubusercontent.com/MinecraftForge/ForgeGradle/v5/gradle/wrapper/gradle-wrapper.properties -o gradle/wrapper/gradle-wrapper.properties curl -s https://raw.githubusercontent.com/MinecraftForge/ForgeGradle/v5/gradle/wrapper/gradlew -o gradlew chmod x gradlew提示这里不执行gradle wrapper因为ForgeGradle v5的wrapper脚本已预置好Gradle 8.2。手动调用会覆盖为8.4导致loom插件兼容性崩溃。2.2 写入精准匹配1.20.1的build.gradle关键在mappings和minecraft版本对齐。Forge-1.20.1对应minecraft 1.20.1forge 47.1.0official-mojang-mappings 1.20.1。以下为精简版build.gradle删减了test、publish等非必要块plugins { id net.minecraftforge.gradle version 5. id org.jetbrains.kotlin.jvm version 1.9.10 apply false // 若不用Kotlin可删 } version 1.0.0 group com.example.mymod repositories { mavenCentral() maven { url https://maven.minecraftforge.net/ } } dependencies { minecraft net.minecraft:minecraft:1.20.1 mappings net.minecraftforge:mappings:1.20.1:47.1.0 implementation fg.deobf(net.minecraftforge:forge:1.20.1-47.1.0) } loom { accessWidenerPath file(src/main/resources/accesswiderner.cfg) }参数说明mappings行必须严格写成1.20.1:47.1.0不能省略冒号后版本fg.deobf()是ForgeGradle v5强制要求的依赖声明方式旧版compileOnly会触发ClassNotFoundExceptionloom块中accessWidenerPath指向一个空文件稍后创建否则gradlew genSources会报null pointer。2.3 执行三步构建链genSources → compileJava → runClient顺序不可颠倒且每步失败必须终止# 第一步生成反混淆源码耗时约2分钟生成src/generated ./gradlew genSources # 第二步编译Java检查语法依赖解析 ./gradlew compileJava # 第三步启动客户端首次会下载1.20.1原版jar约150MB ./gradlew runClient逻辑说明genSources本质是调用loom插件下载minecraft-1.20.1-sources.jar并反混淆到src/generated这是后续compileJava能识别net.minecraft.world.level.block.Block等类的前提runClient会自动注入-Dforge.logging.markersSCAN,REGISTRIES等JVM参数若跳过前两步直接运行IDE会提示Cannot resolve symbol Block。3. Forge-1.20.1的3个必调参数runClient内存、mixin开关、accessWidener路径build.gradle里看似简单的配置实际藏着三个决定项目生死的参数。它们不写在文档首页但90%的“白屏启动”“崩溃日志无堆栈”“Mod不加载”问题都源于此。3.1runClient的JVM内存参数必须显式声明Forge-1.20.1默认仅分配512MB内存而1.20.1原版Forge基础库已超700MB。不调整会导致OutOfMemoryError: Metaspace现象是启动窗口闪退日志末尾只有Process finished with exit code 1// 在build.gradle末尾追加 tasks.named(runClient, JavaExec) { jvmArgs [ -Xms1G, -Xmx3G, // 必须设-Xmx3G以上-Xms建议≥1G避免GC抖动 -XX:UseG1GC, -XX:-UseAdaptiveSizePolicy, -XX:-OmitStackTraceInFastThrow ] }参数说明-Xmx3G是硬性下限实测-Xmx2G在加载5个以上Mod时仍会OOM-XX:-OmitStackTraceInFastThrow禁用异常堆栈优化否则NullPointerException日志里看不到具体行号。3.2mixin插件必须启用且指定refmap1.20.1默认关闭Mixin用于修改原版类字节码但Forge核心Mod如ItemStack增强依赖它。未启用时现象是Mod类被加载但所有Inject方法不执行// 在build.gradle的loom块内添加 loom { mixin { defaultRefmapName mixins.mymod.refmap.json } }然后在src/main/resources/mixins.mymod.json中写入最小配置{ required: true, minVersion: 0.8, package: com.example.mymod.mixin, compatibilityLevel: JAVA_17, mixins: [], client: [], server: [] }注意defaultRefmapName必须与JSON文件名完全一致含大小写否则gradlew build时mixin任务静默失败。3.3accessWidener路径必须指向真实存在的空文件这是最隐蔽的坑loom要求accessWidenerPath指向一个物理文件但内容可以为空。若路径不存在genSources成功但runClient崩溃若路径是目录Gradle报FileNotFoundException# 创建空文件Linux/macOS touch src/main/resources/accesswiderner.cfg # Windows用户用PowerShell New-Item -Path src\main\resources\accesswiderner.cfg -ItemType File血泪经验曾有开发者将文件名拼错为accesswidener.cfg少一个r导致runClient启动后立即退出日志里只有一行Failed to load AccessWidener查了3小时才发现是拼写错误。4. 常见问题排查为什么你的Forge-1.20.1项目总在runClient前崩溃这不是玄学是Gradle构建生命周期与Mojang新签名机制碰撞出的具体故障。以下5条是某开发者在模拟项目X中踩过的真坑按发生频率排序每条附带现象→原因→解决闭环。4.1 现象gradlew runClient报错Could not resolve net.minecraftforge:forge:1.20.1-47.1.0原因Maven仓库URL错误。ForgeGradle v5默认使用https://maven.minecraftforge.net/但部分国内镜像站未同步47.1.0版本截至2024年6月阿里云Maven中心仍缺该版本。解决在build.gradle的repositories块中删除所有镜像站只保留官方源repositories { mavenCentral() maven { url https://maven.minecraftforge.net/ } // 唯一可信源 }验证执行./gradlew --refresh-dependencies后检查~/.gradle/caches/modules-2/files-2.1/net.minecraftforge/forge/1.20.1-47.1.0/是否存在forge-1.20.1-47.1.0-universal.jar。4.2 现象runClient启动后黑屏5秒日志末尾显示java.lang.NoClassDefFoundError: net/minecraft/client/gui/screens/Screen原因minecraft依赖版本与forge不匹配。forge 47.1.0必须搭配minecraft 1.20.1若误写成minecraft 1.20.1字符串而非net.minecraft:minecraft:1.20.1完整坐标Gradle会拉取错误的minecraft-clientjar。解决严格核对build.gradle中minecraft行// ✅ 正确完整Maven坐标 minecraft net.minecraft:minecraft:1.20.1 // ❌ 错误仅版本号触发Gradle默认解析为minecraft-client minecraft 1.20.14.3 现象gradlew genSources成功但src/generated目录为空原因mappings版本号格式错误。1.20.1:47.1.0中的冒号前后不能有空格且47.1.0必须与Forge版本号完全一致Forge官网发布页明确标注47.1.0不是47.1或47.1.0-rc1。解决复制官网发布的精确版本号// ✅ 官网确认的正确写法 mappings net.minecraftforge:mappings:1.20.1:47.1.0 // ❌ 常见错误多空格/少位数/加rc mappings net.minecraftforge:mappings:1.20.1: 47.1.0 mappings net.minecraftforge:mappings:1.20.1:47.1 mappings net.minecraftforge:mappings:1.20.1:47.1.0-rc14.4 现象runClient启动后崩溃日志首行Exception in thread main java.lang.RuntimeException: java.lang.reflect.InvocationTargetException无后续堆栈原因JDK版本不兼容。Forge-1.20.1要求JDK 17.0.1但某些JDK 17.0.0如早期Adoptium构建缺少--enable-preview所需的sealed class支持。解决下载Liberica JDK 17.0.10 https://bell-sw.com/pages/downloads/ 然后在项目根目录创建gradle.propertiesorg.gradle.java.home/path/to/liberica-jdk-17.0.104.5 现象runClient启动成功但游戏内F3调试界面不显示Mod名称/forge mods命令返回空列表原因Mod构造函数参数错误。1.20.1强制要求Mod(mymod)的字符串必须与build.gradle中group值的最后段一致即com.example.mymod→mymod且Mod类必须放在src/main/java/com/example/mymod/包下。解决检查src/main/java/com/example/mymod/MyMod.javaMod(mymod) // ✅ 必须与group的末尾段完全相同 public class MyMod { public MyMod() { IEventBus modEventBus FMLJavaModLoadingContext.get().getModEventBus(); modEventBus.addListener(this::setup); } private void setup(final FMLCommonSetupEvent event) { // 初始化逻辑 } }5. 把runClient变成可调试的IDE工程IntelliJ IDEA中打断点看Block注册全过程光让项目跑起来不够要真正理解Forge-1.20.1的事件驱动机制必须能在IDE里单步调试Block注册。这需要破解两个黑匣子Gradle构建产物的类路径映射、以及runClient进程的远程调试端口。以下是某实验室在模拟项目X中验证过的方案。5.1 生成IDE可识别的.iml和.idea配置ForgeGradle v5不再自动生成IntelliJ配置需手动触发idea任务./gradlew idea注意执行前确保build.gradle中已声明plugins { id idea }v5默认包含。完成后打开mymod-1201.iml检查orderEntry typelibrary nameGradle: net.minecraft:minecraft:1.20.1:sources /是否存在于component nameNewModuleRootManager内。若缺失说明genSources未成功需回退排查。5.2 配置远程调试启动项runClient本质是Java进程可通过-agentlib:jdwp暴露调试端口。在build.gradle中扩展runClient任务tasks.named(runClient, JavaExec) { jvmArgs [ -Xms1G, -Xmx3G, -agentlib:jdwptransportdt_socket,servery,suspendn,address*:5005, // 新增调试参数 -XX:UseG1GC ] }然后在IntelliJ中Run → Edit Configurations → → Remote JVM Debug设置Host: localhost,Port: 5005。启动runClient后再点击Debug按钮即可连接。5.3 在Block注册链上设置3个关键断点以注册一个自定义Block为例真实调试路径如下表。每个断点都能看到Forge如何将你的Java类注入原版世界断点位置类与方法触发时机调试价值1net.minecraft.world.level.block.Blocks.clinit()runClient启动时静态块执行观察原版Blocks.STONE等常量如何被初始化确认minecraft依赖已正确加载2net.minecraftforge.registries.DeferredRegister.register()DeferredRegister.create(...).register(...)执行时看到你的BLOCKS.register(...)如何被包装成RegistryObject验证Mod事件总线是否激活3net.minecraft.world.level.block.state.BlockBehaviour$Properties.of()new Block(BlockBehaviour.Properties.of(...))构造时检查Properties参数如MapColor.STONE是否被正确解析排除NullPointerException实操技巧在断点2处右键Evaluate Expression输入registry.getRegistryKey().location()可实时看到当前注册表名称如minecraft:block确认是否进入正确的Registry上下文。5.4 验证Mod加载成功的终极方法检查logs/debug.log中的REGISTRIES标记Forge-1.20.1的debug.log比旧版更结构化。启动runClient后搜索日志中的REGISTRIES标记[12:34:56] [main/INFO] [REGISTRIES/]: Registering registry minecraft:block [12:34:56] [main/INFO] [REGISTRIES/]: Registered 1234 entries in minecraft:block [12:34:57] [main/INFO] [REGISTRIES/]: Registering registry mymod:block [12:34:57] [main/INFO] [REGISTRIES/]: Registered 1 entries in mymod:block关键指标mymod:block行必须出现且Registered X entries中的X等于你代码中BLOCKS.register()调用次数。若该行缺失说明DeferredRegister未被IEventBus触发大概率是Mod类未被扫描到检查包路径和build.gradle中sourceSets.main.java.srcDirs是否包含src/main/java。我坚持在每次新建Forge-1.20.1项目时先执行./gradlew genSources并手动打开src/generated/net/minecraft/world/level/block/Block.java确认能看到public class Block extends BlockBase {这样的反混淆代码——这是信任构建链的第一步。后来发现只要genSources生成的类能被IDE索引后续所有调试都会事半功倍。希望帮到你。本文还有配套的精品资源点击获取