Minecraft 整合包开服失败排查

17 个模组集体报错,原因是 jar 文件名编码不对

目录

昨晚在 B 站刷到一个整合包,看着挺对胃口,就下载了服务端包 FarmingTales_ForgeⅡ v1.5.2fix2,丢到 MCSManager 里开服。

结果世界都没开始加载,日志里直接刷了 17 个模组加载失败。

报错

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[main/FATAL] [net.minecraftforge.fml.ModLoader/LOADING]: Failed to complete lifecycle event CONSTRUCT, 17 errors found
[main/FATAL] [net.minecraft.server.Main/FATAL]: Failed to start the minecraft server
net.minecraftforge.fml.LoadingFailedException: Loading errors encountered: [
    Create (create) has failed to load correctly
    java.lang.NoClassDefFoundError: Could not initialize class com.simibubi.create.api.contraption.storage.item.MountedItemStorageType,
    Bookshelf (bookshelf) has failed to load correctly
    java.lang.ClassCastException: class net.minecraft.world.item.MobBucketItem cannot be cast to class net.darkhax.bookshelf.mixin.accessors.item.AccessorItem,
    Pufferfish's Skills (puffish_skills) has failed to load correctly
    java.lang.AssertionError: null,
    ModernFix (modernfix) has failed to load correctly
    java.lang.NullPointerException: Cannot invoke "org.embeddedt.modernfix.core.ModernFixMixinPlugin.isOptionEnabled(String)",
    ...
]

第一反应是模组冲突,但 Create、Bookshelf、Puffish、ModernFix 这些互相没什么关系的模组一起挂,而且报错都是 AssertionError、cannot be cast to xxxAccessor 这种,不像是版本不兼容,更像是这些模组的 Mixin 都没起作用。

先排除了几个常见问题

一是文件损坏。把服务器上的 mods/ 和官方 zip 逐个比了 CRC32,280 个文件全部一致。

1
2
3
zip: 280 real: 280
zip-only: 0
real-only: 0

二是 Java 版本。包里有个 tablist-1.0.2.jar 是 Java 21 的字节码,用 Java 17 启动会直接报 UnsupportedClassVersionError,所以这个包必须用 Java 21,面板里用的 mcsm-eclipse-temurin:21 镜像没问题。

三是 Forge 版本,47.4.20,和作者包里的一致。

四是配置,同一份 mods/、config/ 在本地 macOS 上能跑到 Done。

排完这几个就有点怪了,东西都是好的,只有这台机器上开不起来。

Mixin 只注册了 59 个

Forge 启动时会在 logs/debug.log 里打印注册了哪些 Mixin 配置:

1
[main/DEBUG] [mixin/]: Registering mixin config: modernfix-modernfix.mixins.json

数一下条数:

1
2
grep -a "Registering mixin config" logs/debug.log | wc -l
# 59

正常启动应该是 319 条。另外正常日志里一定会有一行 Loading 313 mods:,故障这次也没有,这行是 Puzzles Lib 的 access API 打的,本身就依赖 Mixin。

少了 260 个配置,说明大部分模组的 Mixin 压根没被加载。

jar 文件名不是合法 UTF-8

Forge 是从每个 jar 的 META-INF/MANIFEST.MF 里读 MixinConfigs 的。如果这个名字读不到,模组还是会被加载,类也在,构造方法也会跑,但它的 Mixin 永远不会生效。

写个脚本对着日志里的已注册列表统计一下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import zipfile, os, re

reg = set(open("/tmp/mixin_cfg.txt").read().split())

for root, dirs, files in os.walk("mods"):
    for f in files:
        if not f.endswith(".jar"):
            continue
        try:
            os.fsencode(f).decode("utf-8")
            valid = True
        except UnicodeDecodeError:
            valid = False

        path = os.path.join(root, f)
        mf = zipfile.ZipFile(path).read("META-INF/MANIFEST.MF").decode("utf-8", "replace")
        m = re.search(r"^MixinConfigs:\s*(.+)$", mf, re.M)
        if not m:
            continue

        hit = any(c.strip() in reg for c in m.group(1).split(","))
        print(f"{'UTF8-OK ' if valid else 'UTF8-BAD'} {'registered' if hit else 'MISSING'} {f}")

结果很清楚:声明了 MixinConfigs 的 jar 一共 202 个,文件名是合法 UTF-8 的 10 个全部注册成功,非法的 185 个一个都没注册。还有 6 个名字同样非法的,连 manifest 都读不出来。

这套包是中文命名的([前置]Bookshelf...、[机械动力] create... 这种)。MCSManager 面板在线解压的时候,把这些名字按 GBK 字节写到了 Linux 上。容器里 Java 是 UTF-8 环境,这些路径解析不了,Forge 自然也就读不到 manifest。

至于作者自己开服没事,是因为中文 Windows 的 JVM 用 GBK 处理文件名,同样的字节完全正常。这个包属于在 Windows 上好好的,到 Linux 上必崩。

改文件名

不用重新下载,把文件名转正就行。为了省事,我直接转成了纯 ASCII,反正 Forge 也不看 jar 叫什么名字:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
python3 - <<'EOF'
import os

MODS = "/opt/app/mcsmanager/daemon/data/InstanceData/<实例ID>/mods"

def conv(name: bytes) -> bytes:
    try:
        return name.decode("gbk").encode("utf-8")
    except Exception:
        return bytes(c for c in name if 32 <= c < 127) or b"unnamed"

for root, dirs, files in os.walk(MODS):
    for f in files:
        old = os.path.join(os.fsencode(root), os.fsencode(f))
        try:
            old.decode("utf-8")
            continue
        except UnicodeDecodeError:
            pass

        new = os.path.join(os.fsencode(root), conv(os.fsencode(f)))
        i = 2
        while os.path.lexists(new):
            stem, dot, ext = new.rpartition(b".")
            new = os.path.join(os.fsencode(root), stem + b"-" + str(i).encode() + b"." + ext)
            i += 1
        os.rename(old, new)
EOF

这套包 zip 里的名字本身就是 GBK 和坏字节混着的,有些字符在打包的时候就被换成了 +,想还原成正确中文基本没戏,直接全转 ASCII 最省事。

改完再启动:

1
2
[main/INFO] [Puzzles Lib/]: Loading 313 mods:
[Server thread/INFO] [minecraft/DedicatedServer]: Done (17.176s)! For help, type "help"

Registering mixin config 也回到了 319 条,17 个模组全好了。

另外两个小问题

关掉正版验证之后,用 whitelist add 玩家名 加白名单,玩家还是进不来,日志是 You are not white-listed on this server!。因为原版 whitelist add 写的是正版 UUID,离线模式玩家登录用的是离线 UUID,名字一样也没用。离线 UUID 可以这样算:

1
2
3
4
5
6
7
8
import hashlib, uuid

name = "FGHWETT"
d = hashlib.md5(("OfflinePlayer:" + name).encode()).digest()
b = bytearray(d)
b[6] = (b[6] & 0x0F) | 0x30
b[8] = (b[8] & 0x3F) | 0x80
print(uuid.UUID(bytes=bytes(b)))  # 02d0f227-24d4-3c91-8189-086b52d1ca58

写进 whitelist.json 再 whitelist reload 就行,给 OP 也一样。

另外死亡不掉落和防爆这种 gamerule,懒得每次开服都敲,丢给 KubeJS 每次开服自动设一遍:

1
2
3
4
5
// kubejs/server_scripts/zzz_server_rules.js
ServerEvents.loaded(event => {
  event.server.runCommandSilent("gamerule keepInventory true")
  event.server.runCommandSilent("gamerule mobGriefing false")
})

mobGriefing=false 只挡生物和实体造成的破坏,TNT、床、末影水晶该炸还是炸。

顺便记一下:以后再遇到一批不相关的模组同时报 AssertionError / cannot be cast to xxxAccessor,先去数一下 Mixin 注册了多少个,基本就能定位。Linux 上跑中文整合包的话,解压完最好先检查一下文件名是不是合法 UTF-8。

谢谢支持!
FGHWETT 微信微信