你给服务器加了一个“自动整理箱子”的模组，重启后终端停在一行红字上：Missing or unsupported mandatory dependencies。你把 jar 删了，换了一个“优化生物 AI”的，这次直接 Mixin apply failed。半小时过去，服务器没开起来，模组倒换了四个。
模组比插件更容易“一装就崩”，因为它改的是游戏本身：方块、实体、注册表、启动流程都可能被改。版本、端、依赖只要错一件，服务端就会拒绝启动。
这一页解决“模组装上就崩”：先认加载器，再对版本，最后查冲突。
能装模组的只有 Fabric、Forge、NeoForge、Quilt，目录是
mods/。只装客户端模组，服务端会启动失败或把玩家踢出去，双端模组两边都要装。
MC 版本、加载器版本、Java 版本三者要对上；前置（如 Fabric API）自己补。
装完必须重启；崩了先搜日志关键词，再用二分法关一半找。
模组不是插件：先认加载器#
模组（mod）要挂在模组加载器上运行。Minexa 支持四个加载器，它们各自认自己的模组，互不通用：
| 加载器 | 定位 | 适合 | 要注意 |
|---|---|---|---|
| Fabric | 轻量、更新快 | 追求新版本、轻量模组包 | 很多模组要额外装 Fabric API |
| Forge | 老牌、生态大 | 大型整合包、老版本模组 | 版本线复杂，启动慢 |
| NeoForge | 从 Forge 分出来的继任者 | 较新版本的新整合包 | 不能和 Forge 模组混用 |
| Quilt | 从 Fabric 分出来的分支 | 少量 Quilt 专属模组 | 兼容 Fabric 模组的程度因模组而异 |
判断方法很直接：看模组下载页写的加载器。写 Fabric 的不能丢进 Forge，写 Forge 的也不能丢进 NeoForge。四个加载器的差别见 模组核心：Fabric、Forge、NeoForge、Quilt。
Paper 系核心装的是插件，Fabric/Forge 系核心装的是模组。两者的 jar 都叫 .jar，但入口、API、加载方式完全不同。把 Bukkit 插件丢进 mods/，加载器只会当它是个坏模组；把模组丢进 plugins/，Bukkit 也读不懂。先确认核心类型，再决定放哪个目录。
版本要严丝合缝：MC、加载器、Java#
模组对版本的要求比插件更严格，一个模组能不能加载至少要对上三层：
Minecraft 版本：标着 1.21.1 的模组别指望在 1.21.4 上正常加载，小版本更新也可能改注册表。
加载器版本：模组元数据里会写
fabricloader、forge、neoforge或quilt_loader的最低版本。加载器太旧，模组会拒绝加载。Java 版本：模组按某个 Java 版本编译，服务端 Java 低了会报
UnsupportedClassVersionError。
版本信息藏在 jar 里：Fabric 是 fabric.mod.json，Forge 与 NeoForge 在 META-INF/ 下，Quilt 是 quilt.mod.json。下载页写的支持范围就来自这里。
模组作者通常只维护当前几个 MC 版本。往 1.20.1 的服里装一个标着 1.21 的模组，不是“也许能跑”，而是大概率在启动阶段就崩。选版本的原则是：先定 MC 版本，再选加载器，最后找对应的模组版本。版本对应关系见 游戏版本与 Java 版本。
客户端、服务端、双端：装错端的典型表现#
模组分三种，这是最容易“一装就崩”的地方：
| 类型 | 常见例子 | 装在服务端会怎样 | 装在客户端会怎样 |
|---|---|---|---|
| 仅客户端 | 小地图、界面美化、按键提示、光影相关 | 服务端可能直接崩，或加载后毫无作用 | 正常，只影响自己的画面 |
| 仅服务端 | 区块预生成、备份、服务端小工具 | 正常，客户端不用装 | 客户端装了一般没效果，个别会报错 |
| 双端 | 新方块、新物品、新生物、大多数 API | 正常，但客户端没装就进不来 | 正常，但服务端没装会连不上 |
判断“双端”有个简单办法：新增方块、物品、生物、维度的模组，基本都要双端；只改显示、按键、界面的通常仅客户端；只改服务端逻辑、不新增内容的通常仅服务端。
双端模组最怕版本不一致：服务端 1.0、客户端 1.1，注册表对不上，玩家会被踢或看到错误方块。整合包把它们锁死成一套，更吃内存。
装模组的三种方式#
按你手上文件的形式，选一条：
单个模组：服务端管理 → 插件/模组 → 模组 → 上传，选
.jar；或用文件管理放进服务端目录下的mods/。一次只放一个，装完启动看日志。整合包（mrpack）：下载页 → 导入服务器 → 选
.mrpack。应用会按清单下载服务端文件、校验 SHA-1、跳过仅客户端模组，并应用overrides/和server-overrides/里的配置。从电脑拷：用数据线、FTP 或 MT 管理器，把模组放进
mods/。拷之前先停服，确认电脑上的版本和服务端一致。
三条路装完都一样：停服 → 换文件 → 启动 → 看日志，别在运行中换 jar。
几个硬规则：
不要重复放同一个模组的不同版本。加载器会报重复模组，或者只加载其中一个，行为不可预测。
禁用不是删除。模组开关会把
.jar改名成.jar.disabled，文件还在，配置也还在；启用时改回来。运行中不能启停，先停服。不要解压 jar，也不要只拷 assets 和 data，加载器读的是 jar 包本身。
整合包导入后别急着让朋友进：确认 Java 版本、启动一次、看有没有 Done，再对照手机内存看模组数量。整合包只是把文件准备齐了。
应用只识别 Modrinth 的 .mrpack（压缩包里带 modrinth.index.json）。CurseForge 的整合包格式不在支持范围内；普通的 zip 会被当成“服务端压缩包”导入，里面的模组不会按清单下载。别把 CurseForge 包改个后缀就当 mrpack 用。
装之前的三分钟检查，和删模组的代价#
每次加模组前，花三分钟过一遍下面这张表：
| 检查项 | 怎么确认 | 不通过会怎样 |
|---|---|---|
| MC 版本 | 模组页写的支持范围包含你的服务端版本 | 启动报不兼容，或进服后注册表错乱 |
| 加载器 | 模组写的 Fabric/Forge/NeoForge/Quilt 和核心一致 | 加载器根本不读这个 jar |
| Java 版本 | 服务端 Java 不低于模组要求 | UnsupportedClassVersionError |
| 客户端/服务端 | 确认是仅客户端、仅服务端还是双端 | 装错端直接崩，或玩家进不来 |
| 前置 | 下载页列的依赖都装齐、版本匹配 | Missing dependency / ModResolutionException |
| 备份 | 有一份能回去的整服备份 | 世界被模组改动后无法回退 |
| 空间 | 手机剩余空间大于模组包体积的两倍 | 下载或解压中途失败 |
模组第一次成功启动后，会在服务端目录里留下两类东西：config/（模组自己的配置）和 world/（世界数据，模组新增的方块、实体、维度都写进这里）。改配置前先停服，多数模组不会热读配置。
这就带来一个必须记住的后果：删掉内容模组，世界不会回到装它之前。已经生成的模组方块会变成未知方块，模组实体可能让区块加载失败，少数情况下世界直接打不开。删之前先备份世界；世界已经被改过，最好在备份副本上先试一次能不能开。只删“仅客户端”模组通常不影响服务端世界，因为它本来就没往存档里写东西。
更新模组：小版本直接换，大版本先开新档#
同一 MC 版本内的小更新：通常可以直接替换 jar，重启后看日志。替换前备份
config/，个别更新会改配置键名。跨 MC 版本或大版本更新：注册表和世界格式可能变，直接换 jar 有概率让世界打不开。先在副本上验证能启动、能进服、坐标和建筑正常，再决定要不要动主服。
更新完还要进游戏走一圈：传送、开箱子、触发一次模组功能。启动成功只说明注册表过了，不代表玩法没坏。
依赖与前置：Fabric API 这类东西不能省#
模组依赖是硬门槛。很多模组不是独立程序，它要调用别的模组提供的接口：
Fabric 生态里最常见的硬前置是 Fabric API，大量模组离开它直接加载失败；
跨加载器的公共库（例如 Architectury API）会被多个模组共用；
配置界面库、网络库、渲染库也可能是前置。
下载页通常会写“Dependencies / 需要的前置”。Minexa 不会自动装前置，缺了在启动阶段就报错，Modrinth 安装也只装你选中的那个项目。
缺前置的典型日志：
Missing or unsupported mandatory dependencies:
Mod ID: <前置模组>
Requested by: <你装的模组>net.fabricmc.loader.impl.FormattedException: Mod resolution encountered an incompatible mod set!java.lang.NoClassDefFoundError: <前置模组里的某个类>处理顺序：先看下载页的依赖列表，按它写的名字和版本范围装前置；再确认前置本身也支持你的 MC 版本和加载器；最后重启。不要用旧版本的前置凑合，版本范围不满足时加载器会直接拒绝。
崩了怎么查：先搜日志，再用二分法#
模组崩溃的日志通常很长，但真正有用的就几行：
| 关键词 | 含义 | 处理方向 |
|---|---|---|
Missing dependency / ModResolutionException | 缺前置或前置版本不符 | 按依赖列表补前置 |
Incompatible mod set / requires | 模组组合不兼容 | 看是哪个模组要求哪个版本 |
Mixin apply failed | 两个模组改了同一处代码 | 二分法找冲突，换版本或删一个 |
Duplicate mod | 同一个模组放了多份 | 只留一个版本 |
NoClassDefFoundError / ClassNotFoundException | 缺类，常是前置缺失 | 补前置，确认版本 |
UnsupportedClassVersionError | Java 版本太低 | 换 Java 或换模组版本 |
OutOfMemoryError | 内存不足 | 降模组数量或调内存，见 内存分配 |
Mixin 是模组修改游戏代码的一种技术。两个模组都想改同一个方法时就可能注入失败，日志不会说“谁和谁冲突”，只给一堆类名，所以要用二分法。
二分法：10 分钟定位是哪个模组#
不要一个个删。用“关一半、开一半”的办法，最多几轮就能锁定：
停服并备份。先打一份整服备份，再把当前
mods/的文件名列表抄下来。关掉一半。在模组页把一半的开关关掉（文件会变成
.jar.disabled），启动服务端。看结果。能启动，说明问题在关掉的那一半；不能启动，说明问题在还开着的那一半。
继续对半。把有问题的那一半再分两半，重复第 2–3 步。
锁定单个。只剩一个模组时单独启用验证；确认是它，再查它的依赖和版本。
恢复其余。找到元凶后删掉或换匹配版本，把其余模组按原样开回来，再启动一次确认。
一次只改一个变量，否则分不清是谁救了场：不要一边换模组一边升级 Java。另外，删内容模组前先备份世界，世界已经生成过它的方块或实体，直接删可能让区块加载失败。
手机现实：大型整合包不是不能跑，是很挑#
模组服比原版服吃资源，原因很实在：更多方块、更多实体、更多注册表、更多启动期计算。
4 GB 内存手机：只建议轻量模组包，模组数量控制在几十个以内，分配 1024–1536 MB 堆内存。
6 GB 内存手机：可以跑中小型整合包，分配 1536–2048 MB，视距别开高。
8 GB 及以上：再考虑 2–3 GB 堆内存和更大的包，但仍不建议碰三百个模组以上的大型科技包。
第一次启动模组服要生成世界、初始化注册表，几分钟很正常；超过十分钟还没 Done，先看是不是卡在某个模组的注册阶段。内存给太多也会被系统杀，见 内存分配：给服务器多少 RAM 才够。
终端出现过
Done，且没有Missing dependency、Mixin apply failed这类红字。模组页里的加载器和你的核心一致，
mods/里没有别的加载器的 jar。双端模组在客户端和服务端是同一个版本号。
下载页列出的前置（例如 Fabric API）都在
mods/里。出问题时能按二分法关掉一半模组复现。
装之前有一份能回去的整服备份。
下一步#
四个加载器怎么选、整合包为什么容易崩：模组核心：Fabric、Forge、NeoForge、Quilt
导入
.mrpack的完整流程：导入服务器与整合包已经崩了，想按日志定位：模组冲突与插件报错