常见问题

本章用于集中整理在部署和使用 HyperZoneLogin 时较常遇到的问题。遇到异常时，建议先对照本章判断问题属于哪一类，再结合 配置索引 和 问题反馈 继续排查或整理反馈材料。

加入游戏后提示“登录失败：无效会话（请尝试重启游戏及启动器）”

玩家当前使用的登录方式、会话状态或识别方式，和服务器已安装的验证模块不匹配。

如果提示出现在进入服务器之前，通常应优先排查启动器、账号登录状态或上游会话本身，而不要直接判断为 HyperZoneLogin 故障。

常见原因

未安装 auth-offline，但玩家使用离线方式进入 如果服务器只安装了在线验证相关模块，而玩家实际是通过离线启动方式接入，就可能在认证阶段出现会话不匹配。
正版 / Yggdrasil 玩家会话已过期 如果玩家长时间未重新登录启动器，或游戏客户端保留了过期会话，进入服务器时就可能被上游验证链路判定为无效会话。
离线玩家使用了非常规 UUID 或特殊启动器接入方式 当前离线识别会受到 auth-offline.conf 中匹配规则影响。若启动器使用了不常见的 UUID 生成方式，服务器可能无法按预期识别该玩家。

处理方法

若服务器需要支持离线玩家，请在配置中激活auth-offline模块，然后重启Velocity服务器，并确认相关配置正常生成。
让玩家完全退出游戏和启动器后，重新启动游戏并尝试重新加入服务器。
确认是否只有某一类启动器会出现该问题，然后参照问题反馈中的说明提交反馈，反馈时需补充具体启动器名称、下载链接、登录方式与复现步骤，以及相关服务器日志。

加入游戏后提示“您与`等待后端名称`的连接出现问题。”，服务端日志出现`java.lang.NoSuchFieldError`

日志中的报错应与下方类似：

[HH:mm:ss] [Netty NIO Worker #1/ERROR] [hyperzonelogin]: ToBackendPacketReplacer write failed: Class com.velocitypowered.api.network.ProtocolVersion does not have member field 'com.velocitypowered.api.network.ProtocolVersion MINECRAFT_26_1'
java.lang.NoSuchFieldError: Class com.velocitypowered.api.network.ProtocolVersion does not have member field 'com.velocitypowered.api.network.ProtocolVersion MINECRAFT_26_1'
    at icu.h2l.login.inject.network.ChatSessionUpdatePacketIdResolver.resolve(ChatSessionUpdatePacketIdResolver.kt:42) ~[?:?]
    ...

表示 Velocity 版本过时，不支持 Minecraft 26.1 的网络协议。

请将 Velocity 更新到 3.5.0-SNAPSHOT-584 及以上版本。

无法启动Velocity，服务端日志出现`java.lang.UnsupportedClassVersionError`

日志中的报错应与下方类似：

[HH:mm:ss] [main/ERROR] [com.velocitypowered.proxy.plugin.VelocityPluginManager]: Can't create module for plugin hyperzonelogin
java.lang.UnsupportedClassVersionError: icu/h2l/login/HyperZoneLoginBootstrap has been compiled by a more recent version of the Java Runtime (class file version 68.0), this version of the Java Runtime only recognizes class file versions up to xx.0
    at java.base/java.lang.ClassLoader.defineClass1(Native Method) ~[?:?]
    ...

表示 Java 版本不兼容。HyperZoneLogin 需要使用 Java 24 及以上版本才能运作。

鉴于 Minecraft 26.1 起要求 Java 25 运行，建议直接使用 Java 25 启动服务器。

为什么被封禁的玩家还能绕过封禁？

参见：core.conf

HyperZoneLogin 在玩家等待验证时，会临时把玩家名字改成类似 HZLxxxxxx 的随机名，防止未登录玩家获得过高权限。但不同登录服实现模式下，这个改名对其他插件的影响不一样：

outpre 模式（推荐）：只修改发送给登录服的玩家信息，Velocity 和其他封禁插件看到的还是玩家的真实名字，封禁能正常生效。
backend 模式（备用）：直接在 Velocity 上改名字，因此登陆期间 Velocity 和其他插件（比如封禁插件）看到的都是临时名 HZLxxxxxx。如果此时封禁插件检测到违规，或者会记忆玩家首次登陆时的信息，它封的会是这个临时名，而不是真正的玩家。再加上每次临时名都不一样，玩家只需要再次进服就能绕过封禁。