常见问题

这里是我们实际踩过的坑，按现象查。

一、客户端启动就崩溃

现象：Cannot get config value before config is loaded

原因：模组版本更新了，但旧的配置文件还留在 config/ 里没被替换（常见于背包类模组）。

处理：把该模组的旧配置文件改名或删掉，让它重新生成。例如：

config/travelersbackpack-client.toml
config/travelersbackpack-common.toml
config/travelersbackpack-server.toml

改成 .bak 后缀，重启客户端即可（设置会回到默认值）。

现象：鼠标悬停某个物品就崩

通常是同一个原因（模组在渲染提示条时读配置失败）。按上一条处理。

二、服务端启动失败 / 起不来

现象：Incompatible mods found! + Mod resolution failed

原因：某个模组要求的 Fabric Loader 版本高于服务器装的版本。

我们遇到过的实例：fabric-language-kotlin 要求 Loader ≥ 0.19.5，而服务器是 0.19.3。 关键点：先确认到底有没有模组真的需要它 —— 当时只有纯客户端的 zoomify 需要，所以直接从服务端删掉它就解决了。

现象：两个模组「同 id」导致起不来

同一个模组装了两个版本（例如 xmobs-1.1.3.jar 与 xmobs-1.1.3+26.2.jar）会让 Fabric 直接拒绝启动。 处理：只保留一个（去重）。

三、服务器崩了 / 玩家一用某物品就崩

现象：崩服报告里出现 net.minecraft.client.gui... 之类的客户端类

原因：某些模组声明自己是"双端通用"，但代码里混进了客户端专属逻辑。典型是背包类模组在玩家使用时崩服。

处理：从服务端移除该模组（客户端是否保留另行判断），或等作者修复版本。

四、一卡一卡 / 周期性卡顿

要分两头查：

服务端（所有玩家一起卡）—— 看服务端日志有没有：

Can't keep up! Is the server overloaded? Running ...ms or ... ticks behind
Command execution stopped due to limit (executed 65536 commands)

前者是服务端跟不上（数秒级卡死）；后者是有数据包函数在暴走（每 tick 跑满 65536 条命令上限）。

客户端（只有自己卡）—— 常见原因：

• 光影：开了光影（尤其 Complementary + EuphoriaPatches 这类）在集显/老显卡上会周期性抖动。先关光影测试 5 分钟最有效
• 渲染距离：8 以上 + 光影 = 压力叠加
• 内存分配：机器 16GB 时给游戏 6GB 左右比较稳；给太少会频繁 GC，给太多会影响系统
• 同时开浏览器等吃内存的程序

排查顺序建议：关光影 → 关小地图/结构类模组 → 调渲染距离 → 调内存。一次只改一样。

五、连不上服务器

六、其他

存档/建筑丢了怎么办？ 服务器每天有备份，但回滚需要管理员操作 —— 先找管理员说明情况，不要自己乱动世界文件。

能不能加我想要的模组？ 跟管理员说，评估兼容性后再加。加模组要客户端服务端同步，不是单方面的事。