简介针对 Minecraft 1.20.1 的 Forge 模组开发工具包面向具备 Java 基础、想系统学习模组开发或计划在 1.20.1 版本搭建 Mod 工程的玩家与开发者。压缩包共 17 个文件体积仅 111KB涵盖 Gradle 构建脚本、Java 源码结构、属性配置、Git 规则、变更日志、许可证与贡献名单等。其中面向 Windows 与 Unix 的自动化构建脚本可独立完成编译、打包与测试Gradle 项目配置则统一声明依赖关系、构建逻辑和 JVM 内存等参数帮助开发者保持工程规范。包内源码目录与资源目录的划分还原了 MDK 的标准布局配合变更日志中记录的重要修复与版本演进便于快速定位改动、完成升级适配该包已吸引 1470 人学习下载。对希望从零起步创建首个模组、理解 Forge 开发全流程或维护既有模组工程的开发者来说这套紧凑的工具文件提供了完整且可操作的基础支撑。1. 为什么 1.20.1 是当前最值得停留的模组版本你可能遇到过这种情况装好 Forge双击安装器点了 Install满怀期待打开启动器却发现版本列表里根本没有 Forge 的影子或者在服务器上部署好后开服脚本闪退日志文件里一行报错都看不懂。这不是你操作失误而是 Forge 1.20.1 这套工具链的“匹配规则”比旧版本严格得多——加载器构建号、Minecraft 版本、JDK 版本、启动器参数四条线必须同时对上才能跑起来。之所以还推荐留在这个版本是因为无论是模组数量、模组作者对新玩法的适配速度还是服务端稳定性1.20.1 都是目前平衡点最好的一个。这篇笔记会按“先讲清楚这套工具链怎么匹配再带你一步步装好、配好、排查问题”的顺序把这四个环节一次讲透。想玩整合包的新手能照着走完想自己开服的熟手也能看到参数边界和几个容易翻车的细节。2. 安装 Forge 1.20.1 的完整链路从 JDK 到安装器的四条必检项2.1 JDK 17 是 1.20.1 的硬门槛先确认你的基础环境不少人装完 Forge 后启动器直接弹“找不到 Java 环境”或者“Java 版本不兼容”。原因很可能是系统里装的是 Java 8 或 Java 11——它们能跑旧版 Minecraft但 1.18 之后的版本已经把环境要求提升到了 Java 17。Forge 1.20.1 的所有构建都基于 Java 17 编译安装器本身也需要在这个环境下执行。第一步不是去看安装器而是先确认你现在用的是哪个 JDK。先执行下面这段检查命令java -version # 期望输出中包含 17 字样例如openjdk version 17.0.11 2024-04-16 # 如果输出是 1.8.0 或 11.0.x说明系统默认 JDK 不对如果系统里同时装了好几个 Java 版本单纯执行 java -version 看到 17 还不够还要确认启动器和安装器拿到的 JAVA_HOME 是否指向同一个 JDK 17。常见的做法是在命令行里手动指定路径。例如在 Linux 服务器上安装时我一般会这样设置export JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64 export PATH$JAVA_HOME/bin:$PATH java -version # 确认当前会话生效后再执行安装器 jar避免吃到旧版 JavaWindows 用户如果“安装器双击没反应”多半是 javaw.exe 关联到了旧版本。这时不要在资源管理器里双击而是打开命令行切换到安装器所在目录用 java -jar 手动启动安装器这样控制台会直接打印异常信息方便定位。检查完 JDK 只是第一步接下来要面对的是安装器本身怎么选。2.2 安装器两种模式Install client 与 Install server选错等于白装Forge 的安装器 jar 打开后界面里有 Install client 和 Install server 两个按钮。很多第一次用的人会困惑我明明只在本地玩为什么要分两种模式实际上 client 模式做的事是把 Forge 的版本配置写入你的启动器目录同时把必要的库文件放到 .minecraft/libraries 里server 模式则是生成一份完整的服务端目录里面包含启动脚本和专用的库文件。两者不能混用——你不可能把服务端安装到本地启动器的目录里然后点“开始游戏”。从命令行安装更能看清它到底做了什么。在终端里执行以下命令作用是把 Forge 与当前用户目录下的启动器关联java -jar forge-1.20.1-47.3.0-installer.jar --installClient # --installClient 指定按客户端模式安装 # 安装完成后会在启动器版本列表里多出一个带 forge 的版本 # 如果你用了第三方启动器务必在启动器设置里指定 Minecraft 目录为默认 .minecraft服务端模式则完全不同。它会拉取服务端所需的核心库并生成一个可独立运行的服务端目录。实际操作里很多人以为服务端安装也要在 .minecraft 里执行结果造成了库文件混乱开服时抛出一堆 NoClassDefFoundError。服务端安装应该单独建一个空目录mkdir server-1.20.1 cd server-1.20.1 java -jar /path/to/forge-1.20.1-47.3.0-installer.jar --installServer # --installServer 参数生成 libraries、mods、config、logs 等目录结构 # 执行完后目录里会多出 run.shLinux/macOS或 run.batWindows这段逻辑并不复杂但很多人翻车在没建独立目录就直接在根目录或桌面执行导致各种权限残留。建议你把两种模式分开理解一个是“往现有游戏目录里塞配置”另一个是“生成一个完整的服务器实例”二者互不替代。安装器本身还会根据系统自动选择对应平台的原生库这也是为什么服务端安装最好在与实际运行环境一致的系统上完成。2.3 安装后的目录结构libraries、mods、config、logs 各管什么安装完成后如果你打开 .minecraft 或服务端目录会发现多了一堆文件和文件夹。很多人第一次看到就懵了不知道哪是配置文件、哪是运行时生成的东西。先记住一张目录清单后续排错全靠它。以下以服务端目录为例目录/文件作用出现时间libraries/Forge 与 Minecraft 的核心依赖库体积最大安装器生成mods/存放所有 .jar 模组文件Forge 启动时遍历加载手动创建config/模组和 Forge 自身的配置文件首次启动后生成logs/运行时日志与崩溃报告首次启动后生成eula.txt游戏许可协议首次启动需要改为 true首次启动后生成server.properties服务器端口、人数、视距等核心设置首次启动后生成run.sh / run.bat / run.cmd启动脚本内部已经绑定好了正确的 Java 参数安装器生成注意看表格里的“出现时间”mods 目录默认可能是空的但很多整合包发布时会把 mods 一起打包进来config 和 logs 一定是在你先启动过一次之后才会出现。如果你发现 eula.txt 没生成说明启动还没走到协议确认那一步前面的 Java 或库加载十有八九已经失败了。理解了目录职责下一步就是真正启动它并学会从日志里判断它到底跑了没有。3. 首次启动后的关键输出与核心配置学会看日志和调参数3.1 从 logs/latest.log 读启动状态什么才算“正常跑起来了”不管是客户端还是服务端Forge 启动时都会打一份详细日志到 logs/latest.log。新手打开这个文件经常看到一大串英文直接劝退。但判断是否成功根本不用读全文只要会抓三个关键位置就行。第一个是启动横幅日志开头几行通常会出现 Forge 版本号与 Minecraft 版本号第二个是模组列表加载每个 mod 时都会打印一行 Mod List 信息第三个是最后的加载耗时统计出现类似于“Finished applying ...”“Loading took X seconds”这样的行才说明启动阶段顺利结束。这里给你一组服务端场景下常用的排查命令# 查看 Forge 版本和 Minecraft 版本是否正确匹配 grep -E Forge|Minecraft logs/latest.log | head -5 # 查看最终加载结果/succeeded 或 Done 关键字最直观 grep -E Done|succeeded|Failed to load logs/latest.log | tail -10 # 列出所有已成功加载的模组数量 grep -c Loaded mod logs/latest.log需要注意latest.log 每次启动都会被覆盖所以如果你要看上一次崩溃的完整信息应该看同目录下的 debug.log 或 crash-reports/ 里按时间命名的文件。崩溃报告文件是 .txt 格式文件名带日期时间例如 crash-reports/crash-2025-01-06_12.30.15-server.txt。日志读对了后面解决任何问题都有据可依否则全靠猜。3.2 内存与 JVM 参数-Xmx 不是越大越好-Xms 也别乱设Forge 启动脚本里的 JVM 参数决定了两件事能用多少内存、怎么管理内存。先看一个服务端 run.sh 里常见的默认参数段。直接改 JAVA_ARGS 即可JAVA_ARGS-Xmx6G -Xms4G -XX:UseG1GC -XX:ParallelRefProcEnabled -XX:MaxGCPauseMillis200 # -Xmx6G 最大堆内存 6G超过会抛 OutOfMemoryError # -Xms4G 初始堆内存 4G启动时直接占住避免运行时堆扩容抖动 # -XX:UseG1GC 使用 G1 垃圾收集器Minecraft 服务端公认最稳的选项这里有一个常见的错误认知内存越大越好。实际上 JVM 给 Minecraft 分配超过物理内存一半以上的堆反而容易在系统层面出现交换抖动。比如只有 8G 内存的服务器你开 -Xmx8G 再加上系统与网络开销很快就会卡死。我一般给不同规格机器这样的起步配置物理内存推荐 -Xmx是否启用 G1GC8G4G是16G8G是32G12-16G是且建议把 -Xms 与 -Xmx 设为一致还有一个经常被忽略的参数是 -XX:MaxGCPauseMillis。Forge 服务端在生成区块时临时对象非常多如果 GC 停顿频繁玩家视角就是“突然卡一下”。小服设 200 毫秒比较合适别设太低否则 GC 线程会过度占用 CPU。这些参数改完后一定要重新启动进程才能生效光编辑脚本不会热加载。3.3 首次启动会生成的配置文件eula.txt 与 server.properties 的必填项第一次启动服务端如果你不去改 eula.txt程序会在打印日志后直接退出。这是 Forge 故意设计的合规流程文件里写着“你接受 Mojang 许可吗”。用文本编辑器打开 eula.txt把 false 改成 true然后保存。这一步不完成后面的 server.properties 都没机会看到。紧接着要配置的是 server.properties。这个文件控制服务器对外表现的一切核心参数。注意它只在首次启动成功后生成所以如果你没看到这个文件说明前面某一步其实已经失败了。几个必改的项目看这张表配置项默认值说明server-port25565对外监听端口联机时玩家需要填这个端口online-modetrue正版验证离线服改成 false但强烈不建议公网离线服max-players20服务端允许同时在线的人数上限view-distance10视距单位是区块模组服建议 6-8太高吃内存motdA Minecraft Server服务器列表显示的描述文字很多开服玩家从默认配置直接跑进游戏后发现“局域网可见但外网连不进来”然后开始怀疑端口映射有问题。实际上你先检查 server-port 是否被占用服务端启动日志里如果没有出现类似于“Starting Minecraft server on *:25565”的行就把端口换一个高位端口比如 25575 再试。配置项改完需要重启服务端才会生效。4. 模组安装与 Forge 1.20.1 的 mods 目录管理哪些坑一定会踩4.1 jar 必须直接放 mods 目录不能解压也不能纠结加载顺序Forge 加载模组的方式是遍历 mods 目录下第一层级的所有 .jar 文件注意是“只认最上层”。如果你把 jar 解压成文件夹放进 modsForge 会直接忽略它看起来就像模组没装一样。更隐蔽的问题是“间接放置”有人把另一个整合包的 mods 目录整个拷过来其中的某个模组可能还带内嵌依赖结果加载时报一堆缺类的错误。正确的 mods 目录结构应该是扁平的server-1.20.1/ └── mods/ ├── some-mod-1.0.jar ├── another-mod-2.1.jar └── library-mod-1.0.jar把所有 jar 平铺放进 mods 目录Forge 启动时会自动加载它们。有个误区是以为 Forge 按照文件名顺序加载模组于是有人把前置模组命名为“aaa_xxx.jar”希望它先加载——实际上 Forge 在收集阶段会先建立完整的模组描述表再统一执行构造加载顺序对最终运行并无决定性影响改文件名纯属“玄学”。你在日志里看到的 Mod List 顺序更多是模组自身声明顺序的结果。所以遇到加载问题不要折腾改文件名那是白费功夫。4.2 依赖模组与前置的概念日志里的“Missing or unsupported mandatory dependencies”怎么处理形态比较复杂的玩法模组往往依赖一个或多个前置模组常说“依赖库”。比如有的功能性模组要求先装一个提供基础事件接口的库有的需要图形界面支持库。一旦前置缺失Forge 不会直接让游戏崩溃而是在日志里打出一条缺失依赖的警告然后拒绝加载该模组。你如果进游戏发现某个玩法消失回来看日志会看到很长一段依赖说明关键行类似于Mod X requires Y 1.20.1-1.0.0 or above Currently: no version of Y is present处理这个问题的标准流程分三步。第一步在你下载模组的那个页面里找它声明过的前置需求一般发布页会有一个“Required Dependency”区块第二步确认前置模组的 Minecraft 版本也是 1.20.1很多人只盯主模组版本而忽略前置跑到 1.20.2 上第三步把所有前置 jar 放进 mods 目录再重启。这里最容易的翻车点是“前置版本兼容区间的临界值”有的模组要求前置版本必须大于等于 1.0.0你装的是 1.0.0-beta 或 0.9.9日志照样报缺失。所以下载前置时别只挑最新版要看它是不是正式版、版本号是否满足声明区间。4.3 模组冲突的判断不是所有崩溃都叫“冲突”先看崩溃报告的关键段玩家和服务器管理员常把“游戏崩了”一律归因于模组冲突但在 Forge 1.20.1 里真正因为两个模组同时修改同一类逻辑导致的冲突只占崩溃原因的一小部分。大多数崩溃其实是前置缺失、内存不足、或者模组版本与 Forge 构建不匹配。如何区分看崩溃报告里的一处关键位置——Cause 段。它一般放在报告靠前位置会直接指出导致崩溃的实体类名。举个例子如果报告里出现某个模组特有的类名比如“com.xxx.asm.Transformer”那大概率是字节码变换冲突如果只是“java.lang.OutOfMemoryError”那就无关冲突而是内存问题。一个定位冲突高效率的办法是二分排除法。把 mods 目录下所有 jar 对半分保留一半启动游戏如果正常就说明冲突在另一半再把有问题的半再对半分多试几次就能锁定目标。命令行的做法是把当前 mods 目录做个备份然后用 mv 命令批量移走一半这比在图形界面里逐个勾选快得多cd server-1.20.1/mods # 把当前所有 jar 数量列出来至少应该知道总共有多少 ls *.jar | wc -l # 创建两个临时目录把奇数位与偶数位分开形成两组互斥模组集 mkdir -p ../mods-half1 ../mods-half2 index0 for f in *.jar; do if (( index % 2 0 )); then mv $f ../mods-half1/; else mv $f ../mods-half2/; fi index$((index1)) done # 先用 half1 启动正常则冲突在 half2反之亦然继续二分即可这个方法的逻辑不受模组数量限制几百个模组的服务端也能快速定位。真正开始排查前先把你启动前的 mods 目录用 tar 打个包方便回溯。5. 常见问题与排查手册Forge 1.20.1 的五个实战踩坑记录5.1 现象启动脚本执行后不到十秒退出控制台出现 Exit Code 1这是开服场景里出现最频繁的失败。现象是 run.sh 执行后日志刷几行就直接退出没有完整崩溃报告只有 Exit Code 1。第一次遇到的直接反应往往是“模组坏了”实际排查下来大概率是 Java 环境问题少见的是 libraries 目录被污染。原因是启动脚本内部会调用一个特定的 java 可执行文件如果你手动 export 的 JAVA_HOME 与脚本期望的不一致或者系统默认 java 指向了旧版本就会直接退出。解决方法是先不带任何模组启动也就是把 mods 目录清空后执行一次。清空 mods 仍失败就回到第 2 章的 JDK 检查清空后成功问题就收敛到具体模组上。另外有一种情况是安装器生成的 run.sh 权限不对执行 chmod x run.sh 后再试。5.2 现象运行几小时后日志出现 java.lang.OutOfMemoryError: Java heap space服务端或客户端跑了一段时间后日志里打出这个错误接着服务无响应。很多第一反应是“加内存”但加完还会复现。这个错误的本质是堆内存耗尽但耗尽的模式是有区别的要么是 -Xmx 确实给得太低要么是某个模组存在内存泄漏比如定时任务不断累积对象、地图模组缓存失效区块不释放。解决步骤不能只是改大 -Xmx。先把 G1GC 的日志开关打开观察 GC 回收频率。如果 Full GC 频繁且回收后堆占用率仍停留在高位基本都是泄漏再结合崩溃前日志中最后一次加载的区块或实体类型定位到具体模组。临时止血方案是重启长久方案是给 -Xmx 加 2G 并且更新模组到最新构建因为这类问题经常在新版里被修复。注意很多现成的整合包在发布时默认内存设置是保守的你需要按自己的机器调整而不是无脑相信默认值。5.3 现象局域网玩家报“连接超时”服务端日志却一切正常联机问题里最让人崩溃的就是服务端日志正常、玩家却进不来。这个现象的最常见原因是服务端绑定端口与防火墙规则不一致。Forge 服务端默认端口是 25565但如果你在同一台机器上开过多个服务端可能端口被占用服务端实际会在日志里提示端口冲突并选择随机高位端口。这时你以为还在 25565自然连不上。解决方式分两步。第一步在服务端控制台输入 list 或查看 server.properties 里 server-port 当前值第二步在系统防火墙里放行对应端口而不是只放行 25565。如果你用的是云主机还要检查安全组规则。有一个细节值得提某些系统环境下服务端启动时提示“Permission denied”绑定端口因为非特权用户默认不能绑定小于 1024 的端口。25565 不受影响但如果你因为冲突改成了 255 之类的端口必须换回高位端口或者用 root 启动后者并不值得推荐。5.4 现象安装器下载缓慢或运行时提示文件校验失败下载安装器时网络偶尔波动结果本地拿到的 jar 文件大小不对或校验值不匹配运行时就会打印类似于校验失败的信息。这里有一个血泪教训不要从第三方站点拿二次打包的“整合安装器”那些内容可能被篡改过。正确的应对方式是回到官方渠道下载原始 installer jar再通过官方给出的 SHA-256 校验值核对本地文件。Windows 下可以用 PowerShell 计算Linux 下用 sha256sumsha256sum forge-1.20.1-47.3.0-installer.jar # 将输出结果与官方发布页上的 SHA-256 值比对 # 不一致就删掉重新下载不要强行执行如果你遇到的是安装过程中某个 libraries 小文件下载失败Forge 安装器的逻辑是会直接报错退出但本地已经写了一半的文件会残留。重装前把 .minecraft/libraries 下对应的半截文件清掉否则可能出现校验失败的循环。另外安装器执行时最好把 jar 放在本地磁盘根目录或一个无空格的路径下路径里带中文或空格在个别系统上会引起类加载失败这是比较少见的坑但遇到会让人抓狂。网络环境不理想时直接换一个网络时段再试比反复重试同名文件更有效。5.5 现象启动后卡死在“Preparing level”主城区块迟迟生成不完这个现象在模组服务端第一次启动时尤为常见。表面上日志停在 Preparing level你以为是卡死其实它还在生成区块只是速度极慢。原因主要有两类一类是机器内存不足导致 GC 不断压缩生成线程基本在等待另一类是某个模组在世界生成阶段注入了复杂的维度或结构逻辑导致单区块生成耗时暴涨。排查的第一步是确认它到底有没有在动连续看两次日志的间隔如果一直在刷区块坐标但很慢属于生成效率问题如果完全无输出且 CPU 占用为 0那才可能是死锁。效率问题可以先适当下调 view-distance 到 6 再重启死锁则需要检查模组更新。这里特别提醒第一次生成主城给足时间而不是反复重启。反复重启会导致区块文件写入不完整下次启动反而更慢甚至出现“存档损坏需回退”的提示。6. 验证 Forge 1.20.1 安装是否成功三个小技巧与后续维护习惯6.1 通过 F3 调试界面确认 Forge 版本显示与模组数量进入游戏后按 F3 打开调试界面屏幕左上角通常会有三行文字其中一行会同时显示 Minecraft 版本与 Forge 构建号例如“Minecraft 1.20.1 / Forge 47.3.0”。这一行存在说明 Forge 核心已正常挂载。如果你还装了一堆模组可以按 F3 时同时看右上角或按特定组合键浏览模组列表不过更直接的验证方式是稍后会用到的控制台命令。6.2 服务端控制台查看已加载模组清单服务端启动完成后在控制台输入 recipients 指令往往不是最理想的验证方式。Forge 在启动日志里已经打印了完整的模组列表用下面的命令可以直接提取出来核对既不需要专门指令也能看到模组 ID 和版本号# 在 server 目录下执行列出启动日志中所有 Mod 的 ID 与版本 grep -E ^\[.\] Mod . loaded logs/latest.log # 快速统计 mods 目录 jar 数量与实际加载数量是否一致 ls mods/*.jar | wc -l两边数字对不上就说明有模组因为前置缺失或版本问题被跳过优先处理日志里的警告。整体跑通后再反查 server.properties 里各项参数是否符合预期确保端口、视距、正版验证等关键项没有因为默认值而违规。6.3 日志清理与存档备份开服半年不崩的底牌验证通过只是开始。Forge 1.20.1 服务端运行久了logs 目录会积累大量历史日志crash-reports 也可能囤积很多旧报告占用空间倒是其次主要问题是出问题时你需要看当天那一条太旧的文件会干扰查找。我的习惯是每周写个简单的定时压缩任务把 logs 下七天前的文件压缩归档同时每天对 world 目录打一次增量备份覆盖存档与玩家数据。曾经因为磁盘写满导致一次存档损坏从那以后备份再也没断过。说白了Forge 的安装和调试都是可复现的流程真正区分一个服务端是否稳定要看你会不会在出问题前做这三件事日志留线索、存档留后路、配置改前先备份。希望这些经验能帮到你少走一些弯路。本文还有配套的精品资源点击获取
简介针对 Minecraft 1.20.1 的 Forge 模组开发工具包面向具备 Java 基础、想系统学习模组开发或计划在 1.20.1 版本搭建 Mod 工程的玩家与开发者。压缩包共 17 个文件体积仅 111KB涵盖 Gradle 构建脚本、Java 源码结构、属性配置、Git 规则、变更日志、许可证与贡献名单等。其中面向 Windows 与 Unix 的自动化构建脚本可独立完成编译、打包与测试Gradle 项目配置则统一声明依赖关系、构建逻辑和 JVM 内存等参数帮助开发者保持工程规范。包内源码目录与资源目录的划分还原了 MDK 的标准布局配合变更日志中记录的重要修复与版本演进便于快速定位改动、完成升级适配该包已吸引 1470 人学习下载。对希望从零起步创建首个模组、理解 Forge 开发全流程或维护既有模组工程的开发者来说这套紧凑的工具文件提供了完整且可操作的基础支撑。1. 为什么 1.20.1 是当前最值得停留的模组版本你可能遇到过这种情况装好 Forge双击安装器点了 Install满怀期待打开启动器却发现版本列表里根本没有 Forge 的影子或者在服务器上部署好后开服脚本闪退日志文件里一行报错都看不懂。这不是你操作失误而是 Forge 1.20.1 这套工具链的“匹配规则”比旧版本严格得多——加载器构建号、Minecraft 版本、JDK 版本、启动器参数四条线必须同时对上才能跑起来。之所以还推荐留在这个版本是因为无论是模组数量、模组作者对新玩法的适配速度还是服务端稳定性1.20.1 都是目前平衡点最好的一个。这篇笔记会按“先讲清楚这套工具链怎么匹配再带你一步步装好、配好、排查问题”的顺序把这四个环节一次讲透。想玩整合包的新手能照着走完想自己开服的熟手也能看到参数边界和几个容易翻车的细节。2. 安装 Forge 1.20.1 的完整链路从 JDK 到安装器的四条必检项2.1 JDK 17 是 1.20.1 的硬门槛先确认你的基础环境不少人装完 Forge 后启动器直接弹“找不到 Java 环境”或者“Java 版本不兼容”。原因很可能是系统里装的是 Java 8 或 Java 11——它们能跑旧版 Minecraft但 1.18 之后的版本已经把环境要求提升到了 Java 17。Forge 1.20.1 的所有构建都基于 Java 17 编译安装器本身也需要在这个环境下执行。第一步不是去看安装器而是先确认你现在用的是哪个 JDK。先执行下面这段检查命令java -version # 期望输出中包含 17 字样例如openjdk version 17.0.11 2024-04-16 # 如果输出是 1.8.0 或 11.0.x说明系统默认 JDK 不对如果系统里同时装了好几个 Java 版本单纯执行 java -version 看到 17 还不够还要确认启动器和安装器拿到的 JAVA_HOME 是否指向同一个 JDK 17。常见的做法是在命令行里手动指定路径。例如在 Linux 服务器上安装时我一般会这样设置export JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64 export PATH$JAVA_HOME/bin:$PATH java -version # 确认当前会话生效后再执行安装器 jar避免吃到旧版 JavaWindows 用户如果“安装器双击没反应”多半是 javaw.exe 关联到了旧版本。这时不要在资源管理器里双击而是打开命令行切换到安装器所在目录用 java -jar 手动启动安装器这样控制台会直接打印异常信息方便定位。检查完 JDK 只是第一步接下来要面对的是安装器本身怎么选。2.2 安装器两种模式Install client 与 Install server选错等于白装Forge 的安装器 jar 打开后界面里有 Install client 和 Install server 两个按钮。很多第一次用的人会困惑我明明只在本地玩为什么要分两种模式实际上 client 模式做的事是把 Forge 的版本配置写入你的启动器目录同时把必要的库文件放到 .minecraft/libraries 里server 模式则是生成一份完整的服务端目录里面包含启动脚本和专用的库文件。两者不能混用——你不可能把服务端安装到本地启动器的目录里然后点“开始游戏”。从命令行安装更能看清它到底做了什么。在终端里执行以下命令作用是把 Forge 与当前用户目录下的启动器关联java -jar forge-1.20.1-47.3.0-installer.jar --installClient # --installClient 指定按客户端模式安装 # 安装完成后会在启动器版本列表里多出一个带 forge 的版本 # 如果你用了第三方启动器务必在启动器设置里指定 Minecraft 目录为默认 .minecraft服务端模式则完全不同。它会拉取服务端所需的核心库并生成一个可独立运行的服务端目录。实际操作里很多人以为服务端安装也要在 .minecraft 里执行结果造成了库文件混乱开服时抛出一堆 NoClassDefFoundError。服务端安装应该单独建一个空目录mkdir server-1.20.1 cd server-1.20.1 java -jar /path/to/forge-1.20.1-47.3.0-installer.jar --installServer # --installServer 参数生成 libraries、mods、config、logs 等目录结构 # 执行完后目录里会多出 run.shLinux/macOS或 run.batWindows这段逻辑并不复杂但很多人翻车在没建独立目录就直接在根目录或桌面执行导致各种权限残留。建议你把两种模式分开理解一个是“往现有游戏目录里塞配置”另一个是“生成一个完整的服务器实例”二者互不替代。安装器本身还会根据系统自动选择对应平台的原生库这也是为什么服务端安装最好在与实际运行环境一致的系统上完成。2.3 安装后的目录结构libraries、mods、config、logs 各管什么安装完成后如果你打开 .minecraft 或服务端目录会发现多了一堆文件和文件夹。很多人第一次看到就懵了不知道哪是配置文件、哪是运行时生成的东西。先记住一张目录清单后续排错全靠它。以下以服务端目录为例目录/文件作用出现时间libraries/Forge 与 Minecraft 的核心依赖库体积最大安装器生成mods/存放所有 .jar 模组文件Forge 启动时遍历加载手动创建config/模组和 Forge 自身的配置文件首次启动后生成logs/运行时日志与崩溃报告首次启动后生成eula.txt游戏许可协议首次启动需要改为 true首次启动后生成server.properties服务器端口、人数、视距等核心设置首次启动后生成run.sh / run.bat / run.cmd启动脚本内部已经绑定好了正确的 Java 参数安装器生成注意看表格里的“出现时间”mods 目录默认可能是空的但很多整合包发布时会把 mods 一起打包进来config 和 logs 一定是在你先启动过一次之后才会出现。如果你发现 eula.txt 没生成说明启动还没走到协议确认那一步前面的 Java 或库加载十有八九已经失败了。理解了目录职责下一步就是真正启动它并学会从日志里判断它到底跑了没有。3. 首次启动后的关键输出与核心配置学会看日志和调参数3.1 从 logs/latest.log 读启动状态什么才算“正常跑起来了”不管是客户端还是服务端Forge 启动时都会打一份详细日志到 logs/latest.log。新手打开这个文件经常看到一大串英文直接劝退。但判断是否成功根本不用读全文只要会抓三个关键位置就行。第一个是启动横幅日志开头几行通常会出现 Forge 版本号与 Minecraft 版本号第二个是模组列表加载每个 mod 时都会打印一行 Mod List 信息第三个是最后的加载耗时统计出现类似于“Finished applying ...”“Loading took X seconds”这样的行才说明启动阶段顺利结束。这里给你一组服务端场景下常用的排查命令# 查看 Forge 版本和 Minecraft 版本是否正确匹配 grep -E Forge|Minecraft logs/latest.log | head -5 # 查看最终加载结果/succeeded 或 Done 关键字最直观 grep -E Done|succeeded|Failed to load logs/latest.log | tail -10 # 列出所有已成功加载的模组数量 grep -c Loaded mod logs/latest.log需要注意latest.log 每次启动都会被覆盖所以如果你要看上一次崩溃的完整信息应该看同目录下的 debug.log 或 crash-reports/ 里按时间命名的文件。崩溃报告文件是 .txt 格式文件名带日期时间例如 crash-reports/crash-2025-01-06_12.30.15-server.txt。日志读对了后面解决任何问题都有据可依否则全靠猜。3.2 内存与 JVM 参数-Xmx 不是越大越好-Xms 也别乱设Forge 启动脚本里的 JVM 参数决定了两件事能用多少内存、怎么管理内存。先看一个服务端 run.sh 里常见的默认参数段。直接改 JAVA_ARGS 即可JAVA_ARGS-Xmx6G -Xms4G -XX:UseG1GC -XX:ParallelRefProcEnabled -XX:MaxGCPauseMillis200 # -Xmx6G 最大堆内存 6G超过会抛 OutOfMemoryError # -Xms4G 初始堆内存 4G启动时直接占住避免运行时堆扩容抖动 # -XX:UseG1GC 使用 G1 垃圾收集器Minecraft 服务端公认最稳的选项这里有一个常见的错误认知内存越大越好。实际上 JVM 给 Minecraft 分配超过物理内存一半以上的堆反而容易在系统层面出现交换抖动。比如只有 8G 内存的服务器你开 -Xmx8G 再加上系统与网络开销很快就会卡死。我一般给不同规格机器这样的起步配置物理内存推荐 -Xmx是否启用 G1GC8G4G是16G8G是32G12-16G是且建议把 -Xms 与 -Xmx 设为一致还有一个经常被忽略的参数是 -XX:MaxGCPauseMillis。Forge 服务端在生成区块时临时对象非常多如果 GC 停顿频繁玩家视角就是“突然卡一下”。小服设 200 毫秒比较合适别设太低否则 GC 线程会过度占用 CPU。这些参数改完后一定要重新启动进程才能生效光编辑脚本不会热加载。3.3 首次启动会生成的配置文件eula.txt 与 server.properties 的必填项第一次启动服务端如果你不去改 eula.txt程序会在打印日志后直接退出。这是 Forge 故意设计的合规流程文件里写着“你接受 Mojang 许可吗”。用文本编辑器打开 eula.txt把 false 改成 true然后保存。这一步不完成后面的 server.properties 都没机会看到。紧接着要配置的是 server.properties。这个文件控制服务器对外表现的一切核心参数。注意它只在首次启动成功后生成所以如果你没看到这个文件说明前面某一步其实已经失败了。几个必改的项目看这张表配置项默认值说明server-port25565对外监听端口联机时玩家需要填这个端口online-modetrue正版验证离线服改成 false但强烈不建议公网离线服max-players20服务端允许同时在线的人数上限view-distance10视距单位是区块模组服建议 6-8太高吃内存motdA Minecraft Server服务器列表显示的描述文字很多开服玩家从默认配置直接跑进游戏后发现“局域网可见但外网连不进来”然后开始怀疑端口映射有问题。实际上你先检查 server-port 是否被占用服务端启动日志里如果没有出现类似于“Starting Minecraft server on *:25565”的行就把端口换一个高位端口比如 25575 再试。配置项改完需要重启服务端才会生效。4. 模组安装与 Forge 1.20.1 的 mods 目录管理哪些坑一定会踩4.1 jar 必须直接放 mods 目录不能解压也不能纠结加载顺序Forge 加载模组的方式是遍历 mods 目录下第一层级的所有 .jar 文件注意是“只认最上层”。如果你把 jar 解压成文件夹放进 modsForge 会直接忽略它看起来就像模组没装一样。更隐蔽的问题是“间接放置”有人把另一个整合包的 mods 目录整个拷过来其中的某个模组可能还带内嵌依赖结果加载时报一堆缺类的错误。正确的 mods 目录结构应该是扁平的server-1.20.1/ └── mods/ ├── some-mod-1.0.jar ├── another-mod-2.1.jar └── library-mod-1.0.jar把所有 jar 平铺放进 mods 目录Forge 启动时会自动加载它们。有个误区是以为 Forge 按照文件名顺序加载模组于是有人把前置模组命名为“aaa_xxx.jar”希望它先加载——实际上 Forge 在收集阶段会先建立完整的模组描述表再统一执行构造加载顺序对最终运行并无决定性影响改文件名纯属“玄学”。你在日志里看到的 Mod List 顺序更多是模组自身声明顺序的结果。所以遇到加载问题不要折腾改文件名那是白费功夫。4.2 依赖模组与前置的概念日志里的“Missing or unsupported mandatory dependencies”怎么处理形态比较复杂的玩法模组往往依赖一个或多个前置模组常说“依赖库”。比如有的功能性模组要求先装一个提供基础事件接口的库有的需要图形界面支持库。一旦前置缺失Forge 不会直接让游戏崩溃而是在日志里打出一条缺失依赖的警告然后拒绝加载该模组。你如果进游戏发现某个玩法消失回来看日志会看到很长一段依赖说明关键行类似于Mod X requires Y 1.20.1-1.0.0 or above Currently: no version of Y is present处理这个问题的标准流程分三步。第一步在你下载模组的那个页面里找它声明过的前置需求一般发布页会有一个“Required Dependency”区块第二步确认前置模组的 Minecraft 版本也是 1.20.1很多人只盯主模组版本而忽略前置跑到 1.20.2 上第三步把所有前置 jar 放进 mods 目录再重启。这里最容易的翻车点是“前置版本兼容区间的临界值”有的模组要求前置版本必须大于等于 1.0.0你装的是 1.0.0-beta 或 0.9.9日志照样报缺失。所以下载前置时别只挑最新版要看它是不是正式版、版本号是否满足声明区间。4.3 模组冲突的判断不是所有崩溃都叫“冲突”先看崩溃报告的关键段玩家和服务器管理员常把“游戏崩了”一律归因于模组冲突但在 Forge 1.20.1 里真正因为两个模组同时修改同一类逻辑导致的冲突只占崩溃原因的一小部分。大多数崩溃其实是前置缺失、内存不足、或者模组版本与 Forge 构建不匹配。如何区分看崩溃报告里的一处关键位置——Cause 段。它一般放在报告靠前位置会直接指出导致崩溃的实体类名。举个例子如果报告里出现某个模组特有的类名比如“com.xxx.asm.Transformer”那大概率是字节码变换冲突如果只是“java.lang.OutOfMemoryError”那就无关冲突而是内存问题。一个定位冲突高效率的办法是二分排除法。把 mods 目录下所有 jar 对半分保留一半启动游戏如果正常就说明冲突在另一半再把有问题的半再对半分多试几次就能锁定目标。命令行的做法是把当前 mods 目录做个备份然后用 mv 命令批量移走一半这比在图形界面里逐个勾选快得多cd server-1.20.1/mods # 把当前所有 jar 数量列出来至少应该知道总共有多少 ls *.jar | wc -l # 创建两个临时目录把奇数位与偶数位分开形成两组互斥模组集 mkdir -p ../mods-half1 ../mods-half2 index0 for f in *.jar; do if (( index % 2 0 )); then mv $f ../mods-half1/; else mv $f ../mods-half2/; fi index$((index1)) done # 先用 half1 启动正常则冲突在 half2反之亦然继续二分即可这个方法的逻辑不受模组数量限制几百个模组的服务端也能快速定位。真正开始排查前先把你启动前的 mods 目录用 tar 打个包方便回溯。5. 常见问题与排查手册Forge 1.20.1 的五个实战踩坑记录5.1 现象启动脚本执行后不到十秒退出控制台出现 Exit Code 1这是开服场景里出现最频繁的失败。现象是 run.sh 执行后日志刷几行就直接退出没有完整崩溃报告只有 Exit Code 1。第一次遇到的直接反应往往是“模组坏了”实际排查下来大概率是 Java 环境问题少见的是 libraries 目录被污染。原因是启动脚本内部会调用一个特定的 java 可执行文件如果你手动 export 的 JAVA_HOME 与脚本期望的不一致或者系统默认 java 指向了旧版本就会直接退出。解决方法是先不带任何模组启动也就是把 mods 目录清空后执行一次。清空 mods 仍失败就回到第 2 章的 JDK 检查清空后成功问题就收敛到具体模组上。另外有一种情况是安装器生成的 run.sh 权限不对执行 chmod x run.sh 后再试。5.2 现象运行几小时后日志出现 java.lang.OutOfMemoryError: Java heap space服务端或客户端跑了一段时间后日志里打出这个错误接着服务无响应。很多第一反应是“加内存”但加完还会复现。这个错误的本质是堆内存耗尽但耗尽的模式是有区别的要么是 -Xmx 确实给得太低要么是某个模组存在内存泄漏比如定时任务不断累积对象、地图模组缓存失效区块不释放。解决步骤不能只是改大 -Xmx。先把 G1GC 的日志开关打开观察 GC 回收频率。如果 Full GC 频繁且回收后堆占用率仍停留在高位基本都是泄漏再结合崩溃前日志中最后一次加载的区块或实体类型定位到具体模组。临时止血方案是重启长久方案是给 -Xmx 加 2G 并且更新模组到最新构建因为这类问题经常在新版里被修复。注意很多现成的整合包在发布时默认内存设置是保守的你需要按自己的机器调整而不是无脑相信默认值。5.3 现象局域网玩家报“连接超时”服务端日志却一切正常联机问题里最让人崩溃的就是服务端日志正常、玩家却进不来。这个现象的最常见原因是服务端绑定端口与防火墙规则不一致。Forge 服务端默认端口是 25565但如果你在同一台机器上开过多个服务端可能端口被占用服务端实际会在日志里提示端口冲突并选择随机高位端口。这时你以为还在 25565自然连不上。解决方式分两步。第一步在服务端控制台输入 list 或查看 server.properties 里 server-port 当前值第二步在系统防火墙里放行对应端口而不是只放行 25565。如果你用的是云主机还要检查安全组规则。有一个细节值得提某些系统环境下服务端启动时提示“Permission denied”绑定端口因为非特权用户默认不能绑定小于 1024 的端口。25565 不受影响但如果你因为冲突改成了 255 之类的端口必须换回高位端口或者用 root 启动后者并不值得推荐。5.4 现象安装器下载缓慢或运行时提示文件校验失败下载安装器时网络偶尔波动结果本地拿到的 jar 文件大小不对或校验值不匹配运行时就会打印类似于校验失败的信息。这里有一个血泪教训不要从第三方站点拿二次打包的“整合安装器”那些内容可能被篡改过。正确的应对方式是回到官方渠道下载原始 installer jar再通过官方给出的 SHA-256 校验值核对本地文件。Windows 下可以用 PowerShell 计算Linux 下用 sha256sumsha256sum forge-1.20.1-47.3.0-installer.jar # 将输出结果与官方发布页上的 SHA-256 值比对 # 不一致就删掉重新下载不要强行执行如果你遇到的是安装过程中某个 libraries 小文件下载失败Forge 安装器的逻辑是会直接报错退出但本地已经写了一半的文件会残留。重装前把 .minecraft/libraries 下对应的半截文件清掉否则可能出现校验失败的循环。另外安装器执行时最好把 jar 放在本地磁盘根目录或一个无空格的路径下路径里带中文或空格在个别系统上会引起类加载失败这是比较少见的坑但遇到会让人抓狂。网络环境不理想时直接换一个网络时段再试比反复重试同名文件更有效。5.5 现象启动后卡死在“Preparing level”主城区块迟迟生成不完这个现象在模组服务端第一次启动时尤为常见。表面上日志停在 Preparing level你以为是卡死其实它还在生成区块只是速度极慢。原因主要有两类一类是机器内存不足导致 GC 不断压缩生成线程基本在等待另一类是某个模组在世界生成阶段注入了复杂的维度或结构逻辑导致单区块生成耗时暴涨。排查的第一步是确认它到底有没有在动连续看两次日志的间隔如果一直在刷区块坐标但很慢属于生成效率问题如果完全无输出且 CPU 占用为 0那才可能是死锁。效率问题可以先适当下调 view-distance 到 6 再重启死锁则需要检查模组更新。这里特别提醒第一次生成主城给足时间而不是反复重启。反复重启会导致区块文件写入不完整下次启动反而更慢甚至出现“存档损坏需回退”的提示。6. 验证 Forge 1.20.1 安装是否成功三个小技巧与后续维护习惯6.1 通过 F3 调试界面确认 Forge 版本显示与模组数量进入游戏后按 F3 打开调试界面屏幕左上角通常会有三行文字其中一行会同时显示 Minecraft 版本与 Forge 构建号例如“Minecraft 1.20.1 / Forge 47.3.0”。这一行存在说明 Forge 核心已正常挂载。如果你还装了一堆模组可以按 F3 时同时看右上角或按特定组合键浏览模组列表不过更直接的验证方式是稍后会用到的控制台命令。6.2 服务端控制台查看已加载模组清单服务端启动完成后在控制台输入 recipients 指令往往不是最理想的验证方式。Forge 在启动日志里已经打印了完整的模组列表用下面的命令可以直接提取出来核对既不需要专门指令也能看到模组 ID 和版本号# 在 server 目录下执行列出启动日志中所有 Mod 的 ID 与版本 grep -E ^\[.\] Mod . loaded logs/latest.log # 快速统计 mods 目录 jar 数量与实际加载数量是否一致 ls mods/*.jar | wc -l两边数字对不上就说明有模组因为前置缺失或版本问题被跳过优先处理日志里的警告。整体跑通后再反查 server.properties 里各项参数是否符合预期确保端口、视距、正版验证等关键项没有因为默认值而违规。6.3 日志清理与存档备份开服半年不崩的底牌验证通过只是开始。Forge 1.20.1 服务端运行久了logs 目录会积累大量历史日志crash-reports 也可能囤积很多旧报告占用空间倒是其次主要问题是出问题时你需要看当天那一条太旧的文件会干扰查找。我的习惯是每周写个简单的定时压缩任务把 logs 下七天前的文件压缩归档同时每天对 world 目录打一次增量备份覆盖存档与玩家数据。曾经因为磁盘写满导致一次存档损坏从那以后备份再也没断过。说白了Forge 的安装和调试都是可复现的流程真正区分一个服务端是否稳定要看你会不会在出问题前做这三件事日志留线索、存档留后路、配置改前先备份。希望这些经验能帮到你少走一些弯路。本文还有配套的精品资源点击获取
