
在线UUID修复
此模组在登录时拦截UUID分配,并从Mojang API获取真实UUID,对于离线账户或API无法访问时回退到原版离线UUID。
Online UUID Fix
警告: 在安装此模组或进行任何 UUID 迁移之前,请务必备份你的整个世界文件夹。UUID 变更会影响玩家数据、进度、统计数据和宠物归属。没有自动回滚功能。
注意: 此模组的代码是在 AI(Anthropic 的 Claude)的协助下生成的。使用风险自负,在生产服务器上部署前请审查代码。
一个面向离线模式服务器的 Fabric 服务端模组,为玩家分配其真实的 Mojang/Microsoft UUID,而非原版的离线 UUID。
当服务器以离线模式(online-mode=false)运行时,Minecraft 会使用本地哈希根据玩家用户名生成 UUID。这意味着同一玩家获得的 UUID 会与在线模式服务器上的不同,从而破坏与在线服务器玩家数据的兼容性,并在玩家更换用户名时引发问题。
此模组在登录时拦截 UUID 分配,从 Mojang API 获取真实 UUID,对于非 Mojang 账户或 API 无法访问的情况,则回退到原版离线 UUID。
环境要求
- Minecraft 1.21.11
- Fabric Loader 0.18.2+
- 仅服务端 —— 无需安装在客户端
安装
- 从发布页面下载
modid-1.0.0.jar,或自行构建(见下文) - 将其放入服务器的
mods/文件夹 - 启动服务器 —— 无需任何配置
模组会在玩家首次登录时记录解析出的 UUID:
[OnlineUuidFix] Resolved Steve -> xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
UUID 查询结果会缓存到 config/online-uuid-fix/uuid-cache.json,这样每个用户名只会调用一次 Mojang API。
从源码构建
要求:JDK 21(Eclipse Adoptium —— 安装 JDK,而非 JRE)
# Windows — 如果你同时安装了 JDK 和 JRE,请设置 JDK
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21.0.10.7-hotspot"
./gradlew build
输出的 jar:build/libs/modid-1.0.0.jar
将现有服务器迁移到在线 UUID
如果你的服务器已经以离线 UUID 存储了玩家数据,你需要将这些文件重命名为正确的在线 UUID,否则玩家将从零开始。
玩家数据存储在:
world/playerdata/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.dat
world/advancements/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json
world/stats/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json
分步迁移
1. 找到每个玩家的离线 UUID(当前文件名)
文件名即服务器分配的 UUID。列出 world/playerdata/ 以查看所有文件。
2. 找到玩家的真实在线 UUID
在 namemc.com 查询,或直接使用 Mojang API:
https://api.mojang.com/users/profiles/minecraft/<username>
响应中的 id 字段即为不带连字符的 UUID —— 按 8-4-4-4-12 的模式插入连字符。
你也可以使用以下计算器:
https://minecraft.wiki/w/Calculators/Player_UUID
3. 重命名文件
在服务器停止的情况下,重命名每个文件:
world/playerdata/<offline-uuid>.dat → world/playerdata/<online-uuid>.dat
world/advancements/<offline-uuid>.json → world/advancements/<online-uuid>.json
world/stats/<offline-uuid>.json → world/stats/<online-uuid>.json
4. 安装此模组后启动服务器
新的登录将获得在线 UUID,与重命名后的文件相匹配。
迁移未涵盖的内容
宠物与已驯服的动物
宠物归属以主人的 UUID 存储在宠物的 NBT 数据中。重命名玩家文件后,宠物仍会引用旧的离线 UUID,不会将玩家识别为主人。
有两种修复方法:
方案 A —— 游戏内命令(服务器需运行中)
站在宠物旁边并运行:
/execute as @e[type=wolf,distance=..10] run data modify entity @s Owner set from entity @p UUID
这会将 10 格范围内所有狼的归属重新分配给最近的玩家。将 wolf 替换为其他宠物类型(如 cat、parrot、horse),并按需调整距离。
方案 B —— NBTExplorer(服务器需离线)
使用 NBTExplorer 直接编辑世界 NBT 数据:
- 在区域文件中搜索旧的离线 UUID 字符串
- 将每一处替换为新的在线 UUID
进度
进度存储在单独的 .json 文件中(不在 .dat 内)。这些文件同样需要重命名 —— 见上文第 3 步。
其他玩家的物品栏
如果你需要将一名玩家的物品栏复制给另一名玩家(例如合并账户):
- 备份两个
.dat文件 - 将源玩家的
.dat复制并重命名为目标玩家的 UUID - 目标玩家随后将拥有源玩家的物品栏、经验和位置
这不会转移宠物归属 —— 见上文说明。
工作原理
此模组通过 Mixin 注入到 net.minecraft.core.UUIDUtil.createOfflinePlayerUUID。每当服务器要从用户名生成离线 UUID 时,模组会先查询 Mojang API(api.mojang.com/users/profiles/minecraft/<name>)。如果返回结果,则使用该 UUID。如果 API 返回 404(无 Mojang 账户)或无法访问,则回退使用原版离线 UUID。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。