企业官网建设流程全解析

简介：这份资源是面向Minecraft 1.20.1模组开发者的Forge MDK工具包，适合希望快速搭建开发环境、理解工程结构并着手编写模组的中级Java学习者。压缩包共17个文件，约111KB，以txt说明文档、gradle构建配置、java示例源码、properties参数文件为主，并包含批处理与Shell启动脚本、Gradle Wrapper相关组件及jar、mcmeta等辅助文件，覆盖从项目初始化、依赖声明到构建打包的基础环节。已有1519人学习下载，说明其在模组开发入门与版本适配上具有一定参考价值。借助包内的构建脚本和配置模板，读者可较快完成开发环境搭建，理清源码目录与资源组织方式，并依据变更日志和许可说明了解版本差异与使用边界，减少在环境配置和工程结构上的试错成本。

1. 版本坑：forge-1.20.1 装不起来，多半是 Java 和安装器选错了

上周帮人处理一个 forge-1.20.1 的环境，双击安装器，窗口一闪就没了，日志里只有一行UnsupportedClassVersionError。这类问题在 MC Forge 的安装里出现频率极高：1.20.1 是 1.20 系列里模组生态最全的一个版本，装的人最多，但它对 Java 版本的要求卡得很死。机器上同时存在 JDK 8、JDK 17、JDK 21 的时候，双击 jar 到底用哪一份 JDK，全看系统环境变量当前指向谁，结果就像碰运气。装不对的表现也很统一：安装器闪退、启动器里根本看不到1.20.1-forge这个配置、或者勉强进了游戏，在加载界面卡成黑屏。下面按我自己装机的顺序写，从 JDK 选型、安装器落地、启动器参数，一直写到服务端和日志验证，第一次碰 forge-1.20.1 的人能照着走完，装过几遍还在报错的人也能对上号。

2. 环境准备：JDK 17、内存和目录，三样先定死

装 Forge 之前先把环境定下来，比装到一半再回头改省事得多。这一章只做三件事：确认 Java 版本、把 JDK 17 装到干净路径、规划内存和目录。三件事都是几分钟的活，但漏掉任何一件，后面都会以「安装器闪退」「启动到一半 OOM」的形式找回来。

2.1 JDK 版本对照：1.20.1 只认 17 这条线

先看一张对照表，做整合包或者同时维护多个版本的机器，最好把这张表贴在桌面上：

1.20.1 这一档没有商量余地，就是 Java 17。我见过有人图省事拿 Java 21 去跑 forge-1.20.1，崩得很干脆：Forge 自带的 ASM 和 Mixin 版本读不懂 21 编译出来的 class 文件，日志里甩一句Unsupported class file major version 65，然后整个启动流程停在那里。也有人反过来用 JDK 8，报的是UnsupportedClassVersionError，因为 Forge 1.20.1 的类是按 17 编译的，8 根本加载不了。这两个报错长得很像，但方向完全相反，先看清日志里的数字再动手。

装之前先确认机器上现在用的是哪一份 Java，别靠猜：

# 看默认 java 的版本，输出 17.0.x 才对 java -version # Windows 用 where，macOS/Linux 用 which，确认到底命中的是哪一份 JDK where java which java # 直接打印 java.home，最准，能看出实际加载的 JDK 目录 java -XshowSettings:properties -version 2>&1 | grep "java.home"

第一行命令的输出里，如果版本号是1.8.0_xxx，说明默认指向 JDK 8；如果是17.0.x，恭喜，省一步。第二条命令的作用是排雷：很多机器 PATH 里塞了三四个 JDK 的 bin 目录，java -version显示的和你以为的不是同一个。第三条命令最实在，java.home打出来的路径就是实际生效的 JDK 根目录，把它和你要用的那份对一下，对不上就说明 PATH 顺序有问题。

注意：Windows 上 PATH 的拼接顺序是从左往右命中第一个，早期的 JDK 安装包会往 PATH 最前面插一条C:\ProgramData\Oracle\Java\javapath，这条会把后面所有配置都盖掉，看到它记得删。

2.2 安装 JDK 17 与多版本共存：路径别带空格和中文

JDK 17 建议单独装一份，别去动系统里已有的 JDK 8，很多老工具还依赖它。安装路径我一般固定在D:\env\jdk-17这种位置，理由是短、纯英文、没有空格。C:\Program Files\Java\...带空格，某些启动器的参数拼接会在这里翻车，路径里带中文更麻烦，日志里全是乱码，排查时连报错都读不出来。

装完设JAVA_HOME，但要注意分寸：如果这台机器还要跑别的 Java 项目，全局改JAVA_HOME会波及它们。更稳妥的做法是全局不动，只在启动器里单独指定 javaw 路径，这一点在 3.3 节展开。

# Windows：JAVA_HOME 指向 JDK 17 根目录，注意不要带 \bin setx JAVA_HOME "D:\env\jdk-17" # 只在当前命令行会话里临时生效，用来验证路径是否可用，不改系统配置 set PATH="D:\env\jdk-17\bin;%PATH%" java -version

# Linux/macOS：写进 ~/.bashrc 或 ~/.zshrc，只影响当前用户 export JAVA_HOME=/opt/jdk-17 export PATH="$JAVA_HOME/bin:$PATH" # 让配置立刻生效，再验证一次 source ~/.bashrc java -version

setx那条是写进用户环境变量的，写完之后当前已经打开的终端不会立刻生效，得新开一个窗口。很多人卡在这儿，改完JAVA_HOME一测还是老版本，以为没改成功，其实是终端缓存。set PATH=...那条只作用于当前窗口，验证路径能不能用足够了，不要拿它当长期方案。Linux 那边注意export后面等号两边不要有空格，JAVA_HOME = /opt/jdk-17这种写法会直接报错。

装完再确认一遍java -version输出的是17.0.x，然后把java.home记下来，后面配启动器要填这个路径下的bin/javaw.exe（Windows）或bin/java（macOS/Linux）。

2.3 内存与目录规划：先算清楚再动手

内存这件事，很多人是崩了才想起来调。forge-1.20.1 本身不吃内存，吃内存的是模组：十几个轻量模组 4G 够用，五六十个带地形生成、光照优化、实体增强的整合包，6G 起步才不至于在区块加载时卡成幻灯片。服务端还要更宽裕一点，因为要同时处理多个玩家的区块请求。

目录也别随手扔。默认的.minecraft在C:\Users\你的用户名\AppData\Roaming\.minecraft，路径深、带中文用户名、还在系统盘，出问题时找日志要多点三层。我一般把它整个挪到D:\mc\1.20.1-forge，一个版本一个目录，模组、配置、存档、日志全在里头，崩了直接打包发人，不用来回问「你的日志在哪」。

# 规划好的目录大概长这样，一个版本一套，互不干扰 D:\mc\1.20.1-forge\ ├─ mods\ # 模组 jar，全部平铺，不要建子文件夹 ├─ config\ # 模组生成的配置，第一次启动后才出现 ├─ logs\ # latest.log 和 debug.log 在这里 ├─ crash-reports\ # 崩溃报告，排查的第一现场 └─ saves\ # 存档

mods目录必须是平铺的，子文件夹里的 jar 不会被加载，这个坑每年都有人踩。config目录第一次启动前是空的，属于正常现象，别以为装坏了。logs/latest.log每次启动都会被覆盖，只有debug.log是追加写的，所以崩了之后先拷日志再重启，不然现场就没了。

3. 安装器落地：forge-1.20.1 的图形安装与 --installClient 命令行

环境齐了，进入安装环节。Forge 的安装器本质上做两件事：把 loader 的库文件铺到libraries目录，再往启动器里写一个版本配置。看着简单，但安装器有两种跑法，失败的姿势各不相同，这一章把两种都走一遍。

3.1 拿到安装器先做三件事：文件名、大小、能不能跑

安装器的文件名本身就带信息，格式是forge-1.20.1-47.x.x-installer.jar。前面1.20.1是游戏版本，中间的47是 1.20.1 对应的 loader 主版本线，后面的两个数字是这条线上的迭代号。看到文件名里写着1.20.4或者47以外的数字，先别装，版本对不上，装完也是启动器里多一个用不了的配置。

三件事按顺序做：

1. 核对文件名里的游戏版本是不是1.20.1，loader 主版本是不是47；
2. 校验文件完整性，下载中断的 jar 双击没反应，很容易被误判成 Java 问题；
3. 确认能跑起来，用命令行跑一次带--help的调用，能打印帮助就说明 JDK 环境通了。

# Windows PowerShell：算 SHA1，和下载页给的值逐位比对 Get-FileHash .\forge-1.20.1-47.x.x-installer.jar -Algorithm SHA1 # Linux/macOS sha1sum forge-1.20.1-47.x.x-installer.jar

校验这一步很多人跳过，但它能省掉一大类莫名其妙的问题。下载器断在 90% 的 jar 文件，双击之后窗口一闪就没，日志里连个像样的报错都没有，你会以为是 Java 版本不对，折腾半小时换 JDK，最后发现是文件本身残缺。哈希对不上就重下，别试图修复。

# 确认安装器能被当前 JDK 正常加载，能打印帮助信息就说明环境通了 java -jar forge-1.20.1-47.x.x-installer.jar --help

这一条如果报UnsupportedClassVersionError，回到 2.1 节查 Java 版本；如果报Unable to access jarfile，那是路径写错了或者没切到文件所在目录，跟 Java 无关。

3.2 图形界面安装与命令行安装：--installClient 到底做了什么

安装器有两种跑法。图形界面就是双击 jar，弹出窗口后选「Install client」，确认安装路径，点确定。命令行是加参数直接跑，适合批量装、远程装、以及双击没反应时用来抓日志。

# 客户端安装：不带路径参数时，默认写入系统默认的 .minecraft 目录 java -jar forge-1.20.1-47.x.x-installer.jar --installClient # 指定目录安装：路径里有空格要加引号，这是最容易被忽略的一处 java -jar forge-1.20.1-47.x.x-installer.jar --installClient "D:\mc\1.20.1-forge" # 服务端安装：会生成 libraries、run.sh、run.bat 和 user_jvm_args.txt java -jar forge-1.20.1-47.x.x-installer.jar --installServer

--installClient做的事情比看上去多：往libraries/net/minecraftforge/forge/1.20.1-47.x.x/铺 loader 的依赖库，在versions/1.20.1-forge-47.x.x/下生成同名 json 和 jar，再更新启动器的配置文件，让启动器能识别出这个新版本。所以判断装没装成，最直接的办法就是去versions目录看有没有那个文件夹，有就是装上了。

这里有个前提条件经常被忽略：安装器要往启动器配置里写东西，所以目标目录下必须先有原版 1.20.1 的版本信息，也就是versions/1.20.1/这个文件夹。全新的空目录直接跑安装器，大概率会报找不到启动器配置或者干脆什么都不写。常见做法是先用启动器下载并启动一次原版 1.20.1，进到主菜单退出，再跑 Forge 安装器。

提示：图形界面安装失败时不要反复双击，改用命令行跑同一条命令，报错会直接打在终端里，比看窗口一闪强得多。

3.3 启动器里新建配置：版本、Java 路径、内存三个参数

安装成功之后，启动器的版本列表里会多出1.20.1-forge-47.x.x。很多人的问题出在这一步之后：版本选对了，点启动却报 Java 路径错误，或者进游戏两分钟就内存溢出。原因是启动器默认的 Java 和内存参数跟 Forge 的需求不匹配，得单独给这个配置指定一份。

新建配置时核心是三个参数：版本 id、Java 路径、JVM 参数。不同启动器的字段名有差异，但本质就是这三样，下面用通用结构表示：

{ "name": "1.20.1-forge", "lastVersionId": "1.20.1-forge-47.x.x", "javaDir": "D:\\env\\jdk-17\\bin\\javaw.exe", "javaArgs": "-Xmx6G -Xms2G -XX:+UseG1GC" }

lastVersionId必须和versions目录下的文件夹名完全一致，多一个字符都不行，这是启动器找不到版本的头号原因。javaDir指向 JDK 17 的javaw.exe，注意 Windows 下要用javaw而不是java，前者不弹控制台窗口；路径里的反斜杠在 JSON 里要写成双反斜杠，单反斜杠会被当成转义符解析失败。javaArgs里-Xmx6G是上限，-Xms2G是初始值，两个值不要设成一样大又设得很高，机器内存不够时开机会直接卡死；-XX:+UseG1GC在 6G 以上的堆上比默认收集器少一些停顿，模组多的时候能感觉到差别。

改完参数别急着进游戏，先启动一次，看启动器输出的日志窗口里 Java 版本是不是 17。如果启动器不显示日志，就直接去logs/latest.log头几行找Java Version那一句。

4. 配置收尾：mods 目录、loader 版本区间与服务端 JVM 参数

客户端能进主菜单只是走完一半，真正容易出问题的是加模组和开服务端这两步。这一章处理三件事：服务端怎么装、模组声明的版本区间怎么读、客户端和服务端的 mods 怎么对齐。

4.1 服务端安装：--installServer 与 run.sh 的生成

服务端的安装和客户端是两条独立的路，不要在客户端目录里跑--installServer。单独建一个空目录，进去跑安装器：

# 建一个干净的服务端目录，安装器会往这里铺文件 mkdir -p /opt/mc/1.20.1-forge-server cd /opt/mc/1.20.1-forge-server # 服务端模式安装，需要当前目录可写 java -jar forge-1.20.1-47.x.x-installer.jar --installServer # 安装完成后目录里会出现 run.sh / run.bat 和 user_jvm_args.txt ls -l

装完之后不会立刻有server.jar，这是正常的，Forge 服务端用run.sh作为统一入口，内部再去调用版本对应的启动逻辑。第一次执行run.sh会在当前目录生成eula.txt并直接退出，这是 Mojang 的许可确认机制，不是装坏了。打开eula.txt把eula=false改成eula=true，再跑一次才会真正开始生成世界。

内存参数不在run.sh里改，写在user_jvm_args.txt，一行一个参数，不加引号、不加逗号：

# user_jvm_args.txt，每行一个 JVM 参数，run.sh 会自动读取拼进启动命令 -Xmx6G -Xms6G -XX:+UseG1GC -XX:MaxGCPauseMillis=200

-Xmx和-Xms在服务端设成一样大是常见做法，避免运行中反复扩容带来的卡顿，但前提是这台机器真的有空闲内存，设成一样的 8G 而机器只有 8G 物理内存，系统会开始换页，表现是每隔十几秒全体卡一下。MaxGCPauseMillis是给 G1 的目标停顿时间，200 毫秒对十人以内的服够用，人数上去之后可以适当放宽，别指望它既快又省。

注意：user_jvm_args.txt里不要写-jar和 jar 路径，那些由run.sh负责拼，重复写会导致启动命令错误。

4.2 mods 目录与 loader 版本区间：mods.toml 怎么看

模组放进mods目录之前，先看懂它声明的版本区间，能避掉一大半「加载到一半崩了」的问题。打开任意一个模组 jar（用压缩软件即可），里面有个META-INF/mods.toml，结构大致如下：

# 模组元信息，loader 会在启动时读取并校验 modLoader="javafml" loaderVersion="[47,)" license="All Rights Reserved" [[mods]] modId="example_mod" version="1.0.0" displayName="Example Mod" # 依赖声明：forge 本体和游戏版本都要落在区间内，否则直接拒绝加载 [[dependencies.example_mod]] modId="forge" mandatory=true versionRange="[47,)" ordering="NONE" side="BOTH" [[dependencies.example_mod]] modId="minecraft" mandatory=true versionRange="[1.20.1,1.20.2)" ordering="NONE" side="BOTH"

versionRange="[1.20.1,1.20.2)"这个写法是左闭右开：包含 1.20.1，不包含 1.20.2。所以 1.20.1 的模组塞进 1.20.4 的环境，loader 会在预加载阶段就判定版本不符，日志里给出Missing or unsupported mandatory dependencies并列出具体是哪个 modId 对不上。loaderVersion="[47,)"表示需要 47 及以上的 loader，这也是为什么把 1.20.1 的模组丢到 1.19.2 的环境里必然失败——那边的 loader 主线是 43。

mandatory=true是硬性依赖，缺了直接崩；写成false的属于可选依赖，缺了只是功能少一块。side字段决定这个模组要在哪一侧加载，BOTH是两边都要，CLIENT只在客户端生效。有些模组声明的依赖里带着另一个模组 id，这就是所谓的「前置」，装之前先把前置补齐，比崩了再回头找省事。

4.3 客户端与服务端 mods 对齐：哪些必须两边都装

单机玩不用管这件事，一旦开服，客户端和服务端的 mods 目录就必须分开管理。判断标准看模组本身的功能定位：

判断错的方向有两个。一是把界面模组装进服务端，服务端起来后在加载阶段报NoClassDefFoundError，因为渲染相关的类在服务端环境里根本不存在；二是服务端装了内容模组但客户端没装，玩家一进服就被踢，提示注册表不匹配。第二种更隐蔽，服务端日志干干净净，问题全在客户端。

对齐的做法很土但好用：客户端和服务端的mods目录各自维护一份清单文件，装之前 diff 一下，内容类和前置必须在两边都出现，界面类只在客户端出现。config 目录同理，第一次启动后生成的配置文件两边各留一份，别把客户端的配置直接拷到服务端，有些客户端专属的配置项在服务端读会报解析错误。

5. 排查清单：forge-1.20.1 装崩后的五条血泪记录

前面按正常路径走完了，这一章全是反面案例。以下五条都是我在不同机器上真实遇到过的，按「现象 → 原因 → 解决」写，遇到了直接对号入座。

5.1 安装器双击闪退，命令行报 UnsupportedClassVersionError

现象：双击forge-1.20.1-47.x.x-installer.jar窗口一闪就没，命令行跑同一条命令，终端里打出java.lang.UnsupportedClassVersionError，后面跟着一串类名。

原因：双击 jar 时系统关联的 Java 是 JDK 8，而安装器是用 17 编译的。文件关联和 PATH 里的 java 经常不是同一个，所以「我明明装了 17」和「双击还是用 8」可以同时成立。

解决：不要在图形界面里纠结，改用命令行显式指定 JDK 17 执行。Windows 下写成"D:\env\jdk-17\bin\java.exe" -jar forge-1.20.1-47.x.x-installer.jar --installClient，路径加引号防止空格截断。想彻底解决就去改.jar的默认打开方式，指向 JDK 17 的javaw.exe。

5.2 装完了，启动器列表里没有 1.20.1-forge

现象：安装器提示安装成功，进度条走完，但打开启动器，版本列表里还是只有原版 1.20.1。

原因：多数情况是安装器和启动器指向的不是同一个目录。系统里同时存在官方默认目录和第三方启动器的独立目录时，安装器默认往官方目录写，启动器却从自己的目录读。另一种情况是安装前那个目录里没有原版 1.20.1 的版本信息，安装器写配置时失败但没明显提示。

解决：先确认启动器用的游戏目录在哪，安装时把路径参数显式带上，例如--installClient "D:\mc\1.20.1-forge"。然后去该目录下的versions看有没有1.20.1-forge-47.x.x文件夹，有就手动在启动器里刷新版本列表；没有就说明安装器写错了地方，重装一次。

5.3 加载到一半卡死，日志里是 Mixin apply failed 或 NoSuchMethodError

现象：游戏窗口能起来，加载界面走到一半停住，随后崩溃，crash-reports里第一条是Mixin apply failed或者java.lang.NoSuchMethodError。

原因：模组版本和游戏版本错位。1.20.1 和 1.20.2 之间有几个底层方法签名改过，把给 1.20.2 编译的模组放进 1.20.1，编译期没问题，运行期找不到方法就崩。也有一种是从 1.19.2 的整合包里直接拖过来的模组，版本差得更多。

解决：先看崩溃报告里Mixin apply failed后面跟的模组名，把它单独移出mods再启动一次。能起来就说明是这个模组的问题，回去核对它的下载页写的支持版本，别信整合包里的文件名。批量排查的办法是二分法：一次移出一半模组，能启动就说明问题在另一半，几轮就能定位。

5.4 启动时提示 Missing or unsupported mandatory dependencies

现象：启动阶段直接终止，日志里明确写着缺某个 modId，或者版本区间不满足。

原因：前置模组没装，或者装了但版本太低。4.2 节里mandatory=true的依赖就是这类，loader 在预加载阶段就拦下来，不给进游戏的机会。

解决：照着日志里给出的 modId 和 versionRange 去找对应版本的 jar。注意版本区间是左闭右开的，区间写[47,)就意味着 loader 必须是 47 及以上，装了个 46 的老版本前置照样不满足。补齐之后再看一遍日志，有时候是连锁的，补完 A 又提示缺 B。

5.5 服务端启动几秒后退出，exit code 非零或者根本没有报错

现象：执行./run.sh之后终端刷了几行就退回命令行，没有任何异常堆栈，或者只有一句 Killed。

原因：分两种。第一种是eula.txt还没改成eula=true，这是首次启动的固定流程，但输出很短，容易被当成失败。第二种是内存问题，user_jvm_args.txt里设的-Xmx超过机器可用内存，系统直接杀进程，日志里什么都留不下。

解决：先看当前目录有没有eula.txt，把值改成true再启动。再看user_jvm_args.txt里的堆大小，用free -h或任务管理器确认机器还有多少可用内存，把-Xmx降到物理内存的六成左右。如果日志里出现过OutOfMemoryError: Java heap space，那是堆不够；如果出现的是Metaspace相关，那要调的是-XX:MaxMetaspaceSize，两种不是一个参数。

6. 验证跑通：从 latest.log 的三行关键日志确认环境真的成了

装完不算完，能稳定进游戏、能开服、能加模组才算。验证这一步我从来不看「有没有报错」，而是主动去找几条必须出现的日志，出现了才算过。

客户端的证据全在logs/latest.log里。启动一次之后，用下面这条命令把关键行捞出来：

# Linux/macOS：捞出 loader 版本、模组数量和启动完成三行 grep -E "Forge mod loading|Loading [0-9]+ mods|Done" logs/latest.log # Windows 用 findstr，多个关键词用空格分隔，等价写法 findstr /C:"Forge mod loading" /C:"mods" /C:"Done" logs\latest.log

期望看到的是三类信息：一行说明 Forge 的 loader 版本和对应的游戏版本，形如Forge mod loading, version 47.x.x, for MC 1.20.1；一行说明本次加载了多少个模组，数字应该和你mods目录里的 jar 数量对得上（前置模组会额外计数，差一两个属正常）；最后一行是启动耗时，形如Done (12.345s)!。这三行齐了，客户端基本就没问题。缺第一行说明 loader 没被加载，回去看版本配置；数字明显偏少说明有 jar 没被识别，多半是放进了子文件夹或者文件名带了奇怪的后缀。

服务端的验证点不太一样，Done (xx.xxxs)! For help, type "help"这一句出现在终端里，才代表世界生成完毕、端口已经监听。在那之前终端会刷大量Preparing spawn area: xx%，卡在某个百分比超过两三分钟，通常是地形生成模组在跑，再等等；超过十分钟没动静，就要怀疑是模组冲突。这时候进游戏连一次，能进世界、能破坏方块、退出后服务端不报错，才算真的通。

还有一个容易被忽略的细节：latest.log每次启动都会覆盖，debug.log才是追加的。所以崩了之后第一件事是把logs和crash-reports两个目录整个拷出来，再重启复现，否则现场就没了。这套习惯我是被坑出来的——有一次半夜排查一个模组冲突，重启了五六次才发现原始日志早被覆盖，只能从头再崩一遍。

从那以后我每次装完 forge-1.20.1，不管看起来多顺利，都强制走一遍这套验证：先 grep 三行关键日志，再进一次世界放个方块，最后把 logs 目录复制一份留档。三步加起来不到两分钟，但能把后面几小时的扯皮省掉。希望帮到你。

本文还有配套的精品资源，点击获取