故障排查手册

先保存完整日志，并记录出现问题的玩家、时间和所在服务器。涉及经济或物品时不要先退款、重发或清库。

插件未启用

1. 从日志中找到最早一条 FKEscape 启用失败。
2. 确认 Java 17+ 与目标 Paper 版本。
3. 按角色核对硬依赖：大厅为 Vault、PlaceholderAPI、Citizens；游戏服另需 MythicMobs、MythicLib、MMOItems。
4. 检查数据库地址、账号权限和连接超时。
5. 检查 YAML 缩进、枚举、固定 ID 和跨文件引用。
6. 游戏服确认 game-world 已加载。

预期结果： FKEscape 正常启用，PlaceholderAPI 变量可用，大厅能找到游戏服。

玩家一直排队

依次检查：人数是否达到 min-players；至少一台游戏服是否在线空闲；所有子服是否连接同一个数据库；server-id 是否填写正确；目标服容量和出生点是否足够；玩家库存是否满足报名要求。

关闭一台游戏服进行对照测试：大厅应在心跳过期后停止选择它。若仍选择，优先查身份重复、数据库指向和系统时间。

转服后立即返回大厅

常见原因是玩家绕过大厅直连游戏服、目标服务器名称填写错误、背包购买失败或玩家被送到了错误的子服。

1. 核对游戏服的 server-id 与实际子服名称。
2. 确认所有子服使用同一个数据库。
3. 确认玩家不能绕过大厅直接连接游戏服。
4. 不要再次扣款或手工补发，先查清第一次操作结果。

无票玩家被送回大厅是正常保护结果。

扣款后没有转服或购买后未发货

立即停止玩家重复尝试。查询经济插件流水，按玩家、金额与时间判断是否已经扣款。确认实际结果后只进行一次人工补偿，并记录处理人和流水号。

选装菜单为空或发放失败

• 玩家是否购买该券，或拥有 kits.yml 对应权限。
• 权限是否跨服共享。
• grant-commands 每条是否包含 %player_name%。
• MMOItems 类型/ID、原版命令和执行身份是否正确。
• 是否仍处于 EQUIPMENT 阶段。

把命令逐条在隔离测试服执行，不要对正式玩家重复整组发放。

战利品容器打不开

确认当前为 RUNNING、玩家属于本局、世界和方块坐标完全匹配、坐标处仍是可交互方块、对应池存在。同一容器被其他玩家打开时会锁定，这是预期行为。

若修改了 loot.yml 或 zones.yml，游戏服非空闲时新配置会延至下一局；不要用当前局判断重载失败。

Boss 不生成或条件撤离变灰

检查 MythicMobs 怪物 ID、区域是否允许 Boss、概率与延迟、生成空间和目标撤离引用。Boss 本局不可用时，对应条件撤离也无法使用。始终保留至少一个无需 Boss 的 TIMED 撤离点。

撤离不开始或被中断

检查：阶段是否为行动；玩家是否完整进入同一世界的区域；条件是否解锁；倒计时期间是否受击或离区；受击后是否先离开再重新进入。对照 BossBar 可判断进度是否创建。

伤势、医疗或增益无效

• 医疗品按 MMOItems ID 匹配，不是看显示名。
• 普通金苹果不是专用伤势治疗品。
• 增益品必须由插件生成并携带身份数据，普通 /give 同材质不算。
• 检查 MythicLib 属性名、伤势权重、区域倍率和药水格式 EFFECT:等级:tick。
• extraction.yml、injuries.yml、buffs.yml 重载可影响当前局，修改前应安排维护窗口。

邮箱没有物资或无法领取

只有成功撤离时战术背包物资进入邮箱。原版背包和保险箱不会生成邮件。领取时原版背包必须有空间。

若日志出现撤离物资写入邮箱失败：立即备份数据库与日志，不执行 reset、不清理玩家数据、不重复结算，交由管理员核对后再处理。

保险箱只读

玩家当前最高权限低于历史保险箱档位。恢复原权限即可继续操作；不要缩小 YAML 尺寸或手工搬库。只读是防止降级丢物的设计。

HUD/PAPI 不显示

1. 确认 PlaceholderAPI 在插件前成功启用。
2. 执行 /papi parse me %fkescape_state%。
3. 确认变量前缀是 fkescape。
4. players/state/timer 是本服值。
5. 撤离和死亡统计允许约 5 秒缓存；首次请求可短暂为 0。

故障处理结束条件

• 根因已记录并能在测试环境复现或解释。
• 玩家货币和物品变化已通过数据库与经济流水核对。
• 没有进行重复补偿。
• 大厅与游戏服均已恢复，并通过一次完整测试局。
• 日志与人工处理记录已归档。