安全回退与排错 ​

容器替换优先保证原版菜单可用。只要 ChaUI 无法唯一且安全地建立替换会话，就会保留或恢复原版界面，不会让玩家停留在一个没有真实槽位的假菜单中。

哪些情况会回退原版 ​

• 没有页面匹配当前目标、标题或行数；
• 两个页面比较后仍处于相同最高优先级；
• 服务端确认玩家当前真实容器与客户端候选不一致；
• ChaUI 与 ChaUIMod 协议版本不兼容；
• 页面配置无法解析或未通过校验；
• 替换运行时发生阻止继续安全交互的关键错误。

单张图片缺失只使用普通缺失素材策略，不会因为一个装饰素材不存在就放弃整个替换页面。

Rejected script_event 怎么定位 ​

默认 WARN 会直接给出 player、page、event 和稳定的 reason，例如：

[ChaUI] Rejected script_event: player=q1cent, page=inventory, event=close, reason=lifecycle_id_already_completed

常见原因码包括 missing_lifecycle_id、lifecycle_id_pending、lifecycle_id_already_completed、session_already_has_lifecycle、session_not_found、page_or_session_mismatch、invalid_lifecycle_event 与 lifecycle_id_not_pending。前四项用于区分生命周期 ID 缺失、仍处理中、已完成和同一会话已被占用；会话缺失或页面不匹配则优先检查客户端是否对旧页面发送了关闭事件。

服务端继续使用 config.yml 已有的 debug 配置。开启后，ChaUI logger 的 debug 信息会补充 sessionId、lifecycleId、actionId、source 和服务状态；没有新增第二个调试开关。正常 slot-debug 流水也只在 debug 下显示，真实 payload 损坏、原生槽位读取失败或写入失败仍以 WARN 输出。客户端的正常 slot trace 需要把客户端 logger 调到 DEBUG。

打开后仍是原版界面 ​

按顺序检查：

1. 页面 display.mode 是否为 container。
2. target 是否与当前界面一致：生存背包用 player_inventory，通用箱子用 chest。
3. 箱子标题是否在去掉颜色后仍符合 exact、prefix 或 contains。
4. rows 是否包含当前顶部箱子的真实行数。
5. 是否有另一张页面使用同样的最高优先级和匹配精度。
6. 客户端是否安装与服务端协议一致的 ChaUIMod。

双箱子通常是 6 行，单箱子通常是 3 行。许多插件菜单虽然看起来没有填满，顶部容器仍可能是 6 行，应以真实容器行数为准。

日志提示匹配冲突 ​

冲突不是随机选择失败，而是两张页面同样适合当前容器。处理方式任选一种：

• 给更具体的页面提高 priority；
• 把 any 改成 exact、prefix 或 contains；
• 为已知菜单填写 rows；
• 删除或改名不再使用的重复页面。

修改后重新加载页面配置，再次打开容器验证。

页面打开了，但按钮点错格 ​

确认 containerBinding 从 0 开始。插件所说“第 14 格”通常对应 container_13。还要确认按钮没有被更高 z 的 pointerEvents: block 组件遮挡。

绑定按钮必须保持：

visible: true
enabled: true
pointerEvents: auto
containerBinding: container_13

若 Press 脚本会动态改绑，本次 Click 仍使用按下时捕获的旧槽位，新绑定在下一次点击生效。

名称或 Lore 没有刷新 ​

ChaUI 显示的是原版容器同步后的物品状态。第三方插件处理点击后若替换了菜单物品，等待原版同步到达，名称、Lore、图标和提示会一起刷新。

检查响应式路径是否使用了正确组件 ID：

{vals.container.components.menu_button.name}
{vals.container.components.menu_button.loreText}

若组件已通过脚本解除绑定，对应信息会变为空槽值。

item_slot 无法拖拽 ​

需要完整原版交互时使用绑定的 item_slot，并确认组件启用、参与命中且没有被其他组件遮挡。item_display 只负责展示，button 只代理按钮式槽位点击，二者不会提供完整拖拽操作。

若组件已配置有效 containerBinding，不要用 itemSlot.bind/mode 排查原版槽位：这两个虚拟槽字段会被忽略，旧值即使是 mode: mapped 与 bind: container_0 也不会再触发 mapped 白名单错误。此时应检查 containerBinding 是否在当前容器范围内，以及 itemSlot.check、allowPut、allowTake 是否允许当前操作。交换和数字键替换需要同时允许放入与取出。

reload 后发生了什么 ​

ChaUI reload 不会强行关闭第三方插件容器。当前替换页面会执行一次旧配置的关闭生命周期并释放资源，然后在同一个原版容器上重新匹配：

• 新配置仍匹配：打开新的替换页面；
• 新配置不再匹配：直接显示原版界面；
• 新配置发生冲突或无效：安全回退原版。

若要验证标题或行数变化，最稳妥的方法仍是关闭并重新打开测试容器。

上线前检查清单 ​

• 每个重要插件菜单都有明确标题与行数规则。
• 通用 any 页面使用较低优先级。
• 没有两张玩家背包页面处于相同最高优先级。
• 每个交互按钮都实际点击了第三方插件预期槽位。
• 名称、Lore 和原版 tooltip 在物品变化后能刷新。
• Shift、拖拽、数字键等需求使用 item_slot 测试。
• 缺失素材、配置冲突和协议不一致时都能看到原版界面。

自定义 Tooltip 为什么回到原版 ​

Tooltip 图片仍在加载、素材缺失、GIF、源区或切片非法、屏幕空间不足、平铺片段超过预算，或原生富组件无法无损排版时，ChaUI 会整次回退原版 Tooltip。这是安全行为，不会只留下文字或空背景。先检查服务端 tooltip-styles.yml 与客户端 resourcepacks/ChaUI 素材路径。