猹件开发组安全回退与排错
替换菜单的排错重点不是“为什么整个客户端都坏了”，而是先判断失败发生在哪一层：单个素材、单个目标，还是整个候选包。ChaUI 会尽可能保留可用范围，并让玩家最终回到 Minecraft 原版页面或上一套有效包。
按现象检查
| 现象 | 先检查 | 常见原因 | 修正 | 玩家最终看到什么 |
|---|---|---|---|---|
| 某目标完全没有替换 | 页面的 display.mode、display.vanilla.target、客户端活动包 | 模式不是 vanilla、目标拼错、当前版本不支持目标、页面未发布 | 从目标目录复制 ID，保存或 reload 后再触发原版入口 | 对应 Minecraft 原版页面；其他目标不受影响 |
| 保存时报目标冲突 | 所有 pages/** 中相同 target | 两张或更多页面声明同一目标 | 为每个目标只保留一张页面，或修改其中一张目标 | 冲突目标使用原版，其他目标仍可替换 |
| 页面出现但按钮动作无效 | 事件名、动作名、参数和当前上下文 | 使用了 events.click、目标无效、"true" 写成字符串、在非 confirm 页确认 | 使用 events.leftClick 和本地动作中的真实签名 | 当前页面保持可用；失败动作不会伪造导航 |
close() 没有按预想离开 | 当前目标和 原版.页面.可以返回 | 标题页不能关闭为空页面，连接或加载阶段不允许取消 | 给标题页明确导航；仅在可返回时显示取消按钮 | 保留当前页面或原版上下文，不进入空白 Screen |
| 设置组件显示异常或无法写入 | bind 路径、组件种类、值类型、范围和允许值 | 音量写成 0..100、布尔写成字符串、枚举值不存在、属性只读 | 按原版状态参考和设置绑定修正 | 旧设置值保持不变，其他组件继续工作 |
| 客户端仍使用旧页面包 | 编辑器是否保存成功、手改文件后是否 reload、包摘要是否变化 | 只改了本地素材、手改服务端素材未 reload、新候选未通过校验 | 保存页面；手改 pages/** 或 vanilla-menu-assets/** 后执行 /chaui reload | 继续使用上一套有效包，而不是半套新包 |
| 同步后候选包被拒绝 | 服务端日志和客户端诊断中的首个文件 | YAML/脚本损坏、UTF-8 BOM、摘要或长度不符、路径非法、超出大小限制 | 修复首个失败文件并重新发布；不要手改客户端缓存 | 整个候选包不激活，上一套有效包继续使用 |
| 页面能开但某张图缺失 | 页面相对路径和三个资源来源 | 活动包、ChaAssets、本地资源目录都没有该路径，或大小写不一致 | 按 vanilla-menu-assets/** 镜像路径放置，reload 后复测 | 当前组件使用既有缺失素材策略，页面本身不必退出 |
| 某目标运行一次后回到原版，本次更新中不再替换 | 首次异常前后的客户端诊断 | 页面初始化、脚本、导航或资源生命周期出现关键异常 | 修复页面并发布新的菜单包版本 | 当前包版本内该目标保持原版，避免反复崩溃；其他目标继续工作 |
bootstrap.zip 和活动缓存都无效 | .minecraft/chaui/vanilla-menu/ 下的活动指针、缓存和预置包 | 文件损坏、摘要非法、预置包不是完整 ChaUI 菜单包 | 重新分发有效预置包，或让客户端连接服务器接收有效包 | 不替换任何原版页面，标题页仍可正常使用 |
| reload 或热切换时当前菜单变化 | 新包中是否仍有当前目标 | 页面被删除、目标改变、新页面重建失败 | 确认新包目标与页面有效；重新打开目标复测 | 旧页正常关闭一次；能重建则显示新页，否则恢复原版 |
哪些失败只影响单个目标
以下情况通常只让对应目标回退原版：
- 同一目标有多张冲突页面；
- 目标不受当前 Minecraft 版本支持；
- 某目标运行时发生关键异常；
- 该目标没有配置替换页。
“当前包版本内不再替换”表示 ChaUI 会记住这个目标已经在当前活动包中失败，避免玩家每次进入都重复触发同一异常。发布内容发生变化并成功激活新包后，目标可以重新尝试。
哪些失败会拒绝整个候选包
以下情况会让新候选整体不激活：
- 压缩包、清单、文件长度或摘要不一致；
- 出现不安全路径、重复条目或超出限制；
- 页面不是无 BOM UTF-8；
- 页面 Schema 或脚本无法通过保存级校验；
- 接收不完整或切换未能安全完成。
整包拒绝不会覆盖 active，也不会删除上一套有效包。不要为了“让一部分先用”而手工移动候选文件；修复后重新发布完整包。
素材缺失为何不等于整包损坏
页面引用了包内不存在的 gui/menu/background.png，与包清单声明该文件但实际缺失是两件事：
- 页面只引用了一个未提供路径：当前组件按缺失素材策略回退，并继续查找 ChaAssets 与本地资源目录；
- 清单声称文件存在，但文件长度或摘要不符：候选包本身不完整，整包拒绝。
页面包的服务端、客户端和本地资源目录见页面包与素材。
最小手动验收
发布前至少完成以下检查：
- 启动客户端，确认
title_menu能显示或安全使用原版。 - 进入服务器按 Esc，验证暂停、返回和设置导航。
- 用
打开原版页面("options", true)验证原版保险入口。 - 修改一个设置并正常关闭页面，重启客户端确认保存。
- 发布一份新页面包，确认当前页面热切换或安全恢复原版。
- 在测试环境故意提供一份无法校验的候选包，确认客户端继续使用上一套有效包。