离线模式修复

离线模式修复

[!NOTE] 本项目的活跃开发和源代码托管在 Codeberg。

如果你在其他平台上阅读本文，你看到的是只读镜像。请在官方 Codeberg 仓库中提交所有 issue 和 pull request。

关于

一个轻量级、即插即用的 Fabric 模组，用于修复在离线模式 Minecraft 服务器上游戏时常见的若干客户端问题。

它减少了聊天相关的网络延迟，清理了不安全的聊天指示器，恢复了玩家列表中的玩家头像，抑制了未验证服务器警告，并改善了对某些离线皮肤系统所使用的畸形纹理签名的兼容性。

功能

• 减少聊天延迟： 绕过对离线模式 UUID 不必要的玩家黑名单检查，并禁用可能依赖账号服务的客户端文本过滤检查。
• 离线登录修复： 当本地玩家使用版本 3 离线模式 UUID 时，跳过多人游戏账号服务准备，防止不必要的身份验证请求及相关错误。
• 简洁的聊天界面： 移除聊天消息侧边栏标签，包括未签名消息上显示的红色和灰色“不安全”指示器。
• 玩家头像： 恢复多人游戏玩家列表中的玩家头像渲染。
• 没有烦人的弹窗： 隐藏加入不安全或离线模式服务器时显示的“未验证服务器”警告。
• 更好的离线皮肤兼容性： 绕过对某些离线皮肤系统所使用的已知畸形占位签名格式的严格纹理签名验证。
• 对正版友好： 离线专用的多人游戏准备绕过仅在本地账号使用离线模式 UUID 时启用，因此可以在加入正版模式服务器时保持模组安装。

[!NOTE] 某些客户端调整（例如隐藏聊天标签、禁用文本过滤、恢复玩家列表头像以及抑制未验证服务器警告）无论账号类型如何都保持启用。因此，在正版模式服务器上安装该模组不会完全保留原版客户端行为。

安装

1. 为你的 Minecraft 版本安装 Fabric Loader。
2. 从官方 Modrinth 页面下载适用于你的 Minecraft 版本的 .jar 文件。
3. 将 .jar 文件放入 .minecraft/mods 文件夹。
4. 使用你的 Fabric 配置文件启动游戏。

这些修复本身不需要在服务端安装。

从源代码构建

本项目使用 Stonecutter 从单一代码库支持多个 Minecraft 版本。

你需要：

• Java 25 或更高版本
• Git

1. 克隆仓库

git clone https://github.com/louiszn/offline-mode-fix
cd offline-mode-fix

2. 构建所有支持的版本

在 Linux 或 macOS 上：

./gradlew buildAndCollect

在 Windows 上：

gradlew buildAndCollect

也可以运行各个版本对应的 Gradle 项目来单独构建。

编译后的 .jar 文件位于：

versions/<minecraft-version>/build/libs/

IDE 设置

IntelliJ IDEA

由于 Stonecutter 使用预处理指令在单一代码库中维护多个 Minecraft 版本，建议安装 KikuGie 的 Stonecutter Dev 插件，以获得正确的语法高亮和代码分析。

切换当前开发版本：

1. 打开 Gradle 工具窗口。
2. 导航至 Tasks -> stonecutter。
3. 运行相应的 Set active project to ... 任务。

例如，选择 1.21.11 项目会使该版本在 IDE 中处于活动状态。

工作原理

离线模式服务器可能会暴露若干客户端行为，这些行为通常假设玩家和服务器由 Mojang 账号服务支持。

Offline Mode Fix 应用了一小部分 Mixin 来改变这些行为。

玩家黑名单检查

Minecraft 通常在处理玩家和聊天消息时调用 isBlocked(UUID)。

对于：

• null UUID，
• 离线模式玩家使用的版本 3 UUID，以及
• 系统消息使用的 NIL UUID，

该模组会立即返回 false，而不是执行正常的黑名单检查。

正版 UUID 继续走原版 isBlocked 实现。

文本过滤

该模组重写 isTextFilteringEnabled() 并返回 false。

这会禁用客户端文本过滤路径，并避免依赖账号服务的过滤检查。

此行为目前无论本地账号是离线还是已认证都会应用。

多人游戏准备

加入多人游戏时，Minecraft 通常会运行 prepareForMultiplayer()，该方法会初始化依赖账号的多人游戏服务。

该模组在改变此行为之前会检查本地玩家的档案 UUID。

如果本地档案使用版本 3 离线模式 UUID，则取消准备步骤。

已认证账号继续走正常的原版多人游戏准备路径。

聊天消息标签

该模组拦截添加到聊天 GUI 的消息，并移除其 GuiMessageTag。

这会移除用于未签名或其他已标记消息的侧边栏指示器，包括熟悉的红色和灰色“不安全”指示器。

由于标签本身被移除，这目前会影响所有聊天消息标签，而不仅仅是不安全消息标签。

玩家列表中的玩家头像

该模组强制在多人游戏玩家列表中渲染玩家头像。

这会恢复 Minecraft 在连接被视为不安全时可能隐藏的头像。

未验证服务器警告

该模组拦截客户端弹窗管理器，并阻止显示不安全服务器警告弹窗。

其他弹窗通知不受影响。

纹理签名验证

现代 Authlib 版本会严格验证已签名的纹理属性。

某些离线皮肤系统提供的占位签名不是有效的 Base64 字符串，这可能导致验证错误并阻止纹理正确加载。

当提供的签名包含下划线（_）或空格时，该模组会绕过 YggdrasilServicesKeyInfo.validateProperty()，允许这些已知的畸形占位格式通过验证。

其他签名继续走正常的 Authlib 验证路径。

范围

Offline Mode Fix 有意专注于与离线模式服务器相关的客户端兼容性问题。

它不：

• 为离线模式服务器添加身份验证，
• 保护离线模式服务器免受用户名冒充，
• 替代身份验证插件，
• 修改服务端账号处理，或
• 使离线模式服务器等同于正版模式服务器。

服务器所有者在运行公开可访问的离线模式服务器时，仍应使用适当的身份验证解决方案。

贡献

欢迎贡献。

如果你发现 bug 或有改进想法，欢迎提交 issue 进行讨论。也非常感谢 pull request。

在贡献影响 Minecraft 内部实现的更改时，请牢记多版本兼容性，并尽可能测试相关的 Stonecutter 版本。

许可证

Offline Mode Fix 采用 MIT 许可证。详情请参阅 LICENSE。