问题排查
按加载、入口、重载、数据和导出症状，找到真正生效的修改位置。
菜单加载
先执行：
/invero menu reload
/invero menu list第一条会重新扫描并实际更新菜单，可能使正在查看该菜单的玩家重新打开窗口；第二条列出当前已经加载的 ID。后台日志用于区分工作空间为空、文件格式错误、菜单解析错误、菜单 ID 重复及绑定命令冲突。
| 日志或现象 | 应检查的位置 |
|---|---|
| 没有有效工作空间 | plugins/Invero/config.yml 的 Workspaces.paths；路径相对服务端运行目录，字段缺失不会自动使用随附目录 |
| 配置文件载入出错 | 日志所指文件的格式、引号和缩进，以及扩展名是否真正选择了对应解析格式 |
| 菜单解析失败 | 字段层级与类型；文件需包含顶层 menu 或 title，并有有效面板 |
| 重复菜单 | 显式 id 或不含扩展名的文件名；目录不构成 ID 前缀，重复检查忽略大小写 |
| 保存后仍是旧效果 | 日志中是否自动重载失败；旧菜单仍能打开不表示新配置已经应用 |
常见问题
确认文件位于 Workspaces.paths 的某个目录内、文件名匹配 Workspaces.filter，并含顶层 menu 或 title。随附规则只排除文件名以 # / ! 开头的文件，不排除同名风格的整个目录。新增文件后执行 /invero menu reload，不是只保存文件。
HOCON 内容用 .conf；.hocon 虽在随附筛选内，却按 YAML 回退读取。格式识别区分扩展名大小写；.tml 能按 TOML 读取，但还需加入筛选。详细规则见文件目录。
Workspaces.file-listener 只监听已成功加载的原文件，不是目录发现器。文件新增、删除、移动、改名，或改成 #菜单.yml / !菜单.yml 后执行 /invero menu reload。主配置路径和监听开关修改后需要重启，菜单重载不会重读它们。
菜单 ID 默认来自不含最后扩展名的文件名；不同目录仍共享 ID，Hello 与 hello 也冲突。可以在文件顶层设置不同的 id，标题不用改。
绑定命令检查当前菜单所有 command / commands / cmd / cmds 定义的名称和别名。其他菜单占用相同 Invero 标签时会失败；其他插件占用普通命令时，后台可能提示使用 /invero:<命令名>。不要把菜单 ID 与命令标签当成同一个名称。
这些名字能被配置读取，但不会由实际事件触发。改为 bindings.item、bindings.chat、bindings.adyeshach 后重新加载菜单。四种命令字段名都可以注册命令，不受这个限制。完整字段见菜单打开入口。
物品、聊天、实体、NPC、潜行换手共用每名玩家约一秒的事件间隔，没有匹配成功的尝试也可能占用它。稍后再单独测试一个入口；多个菜单使用相同条件时不提供固定优先顺序。
物品入口只看主手，已有 Invero 会话时不触发；聊天按完整文字匹配，不是包含匹配；shift_f 要在潜行状态切换后的指定毫秒内换手，持续潜行不会不断更新起点。打开被 events.pre_open 拒绝后，也不会重新尝试另一个同条件菜单。见入口实际行为。
entity 填实体类型，如 VILLAGER，不是显示名；adyeshach 填 Adyeshach NPC ID，并要求对应插件可用。NPC 入口使用 adyeshach 而不是 ady。
activator_entity_is_npc 不是通用 NPC 检测，仅识别玩家类型且不在在线列表的实体。完整入口变量见入口变量。
绑定命令的 permission 只限制该命令，不限制其他入口。所有入口的共同打开条件应放到 events.pre_open。
/invero menu 等分支只检查 invero.command.access；独立 /menu 才检查 invero.command.menu。同理，独立 /gnode 与 /idev 的权限不会自动限制主命令中的对应分支。逐项关系见命令与权限。
节点文件必须直接位于 GlobalNodes.paths 的目录里，不扫描下级目录，也不随菜单文件自动重载。文件顶层用 nodes，每个条目用对象；节点名区分大小写。
执行 /invero gnode reload 查看后台具体错误，再用 gnode list 查看结果。重载先清空旧定义，失败节点不会保留。gnode test <节点名> 只显示已加载配置，不执行它。GlobalNodes.priority 只有精确的 menu-first / global-first 才查全局节点，拼写或大小写错误会只查本地节点。见全局节点加载规则。
主配置需要完整重启。已有配置删掉 Workspaces.paths / GlobalNodes.paths 会得到空路径列表，不是恢复随附路径；删掉 Workspaces.filter 后其回退还不包含 TOML；删掉 Paste.service-type 后回退为 pastegg，不是随附选择的 lucko。各项区别见主配置。
SQL 连接使用 Database.sql.user，不是 username，且要填写非空 table。示例占位值必须换成实际连接信息；仅写 type: SQL 而不提供 sql 对象会失败。无法识别的类型（包括 MONGODB）则回退为 SQLite，两种情况不同。
SQLite 文件是 plugins/Invero/data/invero_data.db，不会使用 SQL 的表名字段。改存储类型、库名或表名不会自动迁移数据；确认当前实际连接的位置和启动日志，不要把空新库当成旧数据被删除。见数据库。
lucko 和 Pastebin 只上传物品导出的第一份结构视图。需要三份内容时选择 pastegg 并重启，或者执行 /invero item encodePrint 从后台取得 Base64 与 JSON。encodePrint 仍会联网上传，并非离线导出。
装备位置使用小写 mainhand、offhand、head、chest、legs、feet，不填背包格号。见物品导出。
检查服务端到所选 API 的连接及后台异常。base-url 是 API 地址，不是已经创建好的网页链接；Pastebin 使用自己的 dev-key。修改 Paste 后需要重启，没有独立重载命令。menu dump、gnode dump 和物品导出共用这组设置，见内容导出服务。
普通 Lore 列表和 |- 已经按行书写，不需要增强换行。节点、占位符或单引号文字返回的是文字形式的 \n 时，将 enhancedLore: true 与 lore 写在同一显示配置中；使用 display 时两者都在其下。见物品属性。
自动任务与手动 task 调用的执行范围不同，async 也不把同步网络读取自动变成不等待的动作。按任务核对自动启动、手动调用和 Folia 的适用范围，不要只根据这个字段判断整段动作是否异步。
等级必须是整数。检查附魔名称、HIDE_ENCHANTS、glow、hideTooltip 与导入物品原有属性，见附魔。
action 应在图标层而非 display 下。检查点击类型与条件；def 会和对应点击类型一起执行，不是“仅未匹配时执行”。命令动作中不带开头 /，玩家执行还受目标命令权限限制。对照点击动作并查看后台的具体语句错误。
条件外观与点击许可是不同的配置。外观变化需要重新选择状态并更新显示，不能只刷新标题；按条件状态指南选择对应刷新方式。icons refresh 会重建生成器并回到第一页，不应拿来实现保留当前页的局部更新。
在线名单等生成数据通常在打开时取得；筛选和排序现有数据不等于重新获取名单。先重新打开验证数据是否变化，再按搜索指南区分重新取数、重新筛选与显示刷新。
reopen 用于输入成功后的重开。取消要在 onCancel 中明确配置打开菜单等动作，不会自动走成功分支，见输入收集。
确认使用支持真实物品交互的普通窗口，并按面板局部坐标配置存储格。关闭时存储面板会返还剩余输入；如果又在关闭动作中给同一份物品，会重复发放。检查 storage del 是否已经消费输入、listener 和关闭动作是否重复处理，见交互面板。
提交问题
提供能对应到一次实际操作的资料：
服务端类型与 Java 环境：
相关插件与依赖：
菜单 ID、文件路径与相关配置：
打开方式与使用的命令或交互：
操作步骤：
预期效果与实际效果：
对应时间的完整后台错误日志：导出配置与日志时隐去密码、密钥和玩家私密数据；若问题只在某个入口出现，保留该入口的字段与传入参数。
Last updated on