> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wen-dang/pei-zhi-yu-guan-li/faq.md).

# 常见问题与故障排查

排查前记录所用服务端、玩家客户端版本、执行的命令及完整报错。修改配置前备份相关文件，每次修改后检查并重载，再重新打开菜单验证。

## 插件安装与配置

### 插件未正常启用

先检查控制台启动日志，确认服务端和 Java 符合[运行要求](/arcmenu-wen-dang/ru-men/requirements.md)，且 `plugins/` 中只保留一个 ArcMenu 插件文件。Spigot 首次启动还需要下载必要文件，下载失败时检查网络后重新启动。

更换插件文件需要重启服务端，配置重载不能代替重启。

### 修改后菜单没有变化

确认修改了当前服务端使用的文件：Paper 系服务端使用 `plugins/ArcMenu/menus/`，Spigot 使用 `plugins/ArcMenu/spigot/menus/`。执行 `/arcmenu validate`，修正提示中的错误，再执行 `/arcmenu reload`。

图片、模板或提示框样式变更应按[配置文件说明](/arcmenu-wen-dang/pei-zhi-yu-guan-li/configuration-files.md)执行完整重载。图片变更还需要更新玩家加载的资源包。

### 菜单配置无法通过检查

根据报错中的文件名和字段定位问题。重点检查 YAML 缩进、字段类型、重复菜单标识、无效的菜单跳转目标，以及是否只保留一个 `main-menu: true`。

不要将整个配置参考页的多个片段直接合并成菜单；先使用完整示例，再逐项修改。Spigot 还应检查是否使用了不支持的字段或动作，参见[平台与插件兼容性](/arcmenu-wen-dang/pei-zhi-yu-guan-li/compatibility.md)。

## 打开与操作菜单

### 玩家无法打开菜单

玩家需要 `arcmenu.use`，以及菜单 `permission` 中设置的额外权限。请分别使用管理员和普通玩家账号测试；OP 可以打开并不代表普通玩家已有权限。

Paper 系服务端还要求玩家落地。先站在地面上使用 `/arcmenu open <菜单标识>` 测试，再排查快捷键。

### Shift+F 没有打开主菜单

确认存在一个主菜单，且 `shortcuts.shift-f` 已启用。Paper 系服务端的设置在 `plugins/ArcMenu/config.yml`，Spigot 的快捷键设置在 `plugins/ArcMenu/spigot/config.yml`。

同时确认玩家权限、客户端交换副手按键设置，以及其他插件是否占用了同一操作。命令能够打开菜单时，可先用命令继续测试。

### 按钮显示正常但无法点击

前端按钮与后端点击区域分别配置。检查区域是否与按钮位置、尺寸对应，以及使用的是左键还是右键动作。前端分组、缩放或动画不会自动移动后端区域。

区域重叠时，检查 `priority` 和对应条件。权限或条件未满足时，按钮仍可能显示，但不会执行允许分支。完整说明见[后端交互区域与点击事件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/backend.md)。

### 按钮调用其他插件的命令失败

先让同一玩家直接执行目标命令，检查权限、参数、冷却和费用。`player` 以玩家身份执行；`console` 以控制台身份执行，需要自行填写目标玩家参数。

ArcMenu 不会自动授予第三方命令权限，也不会保证命令执行成功。配置方式见[插件联动菜单示例](/arcmenu-wen-dang/cai-dan-shi-li/integration-menu.md)。

## 图片、鼠标与文字

### 图片缺失或仍显示旧图片

确认图片引用对应 `images/` 中的 PNG 文件，名称和子目录使用小写。执行 `/arcmenu reload all` 重建资源，并将更新后的资源包分发给玩家。

使用 CraftEngine 时，随后执行 `/ce reload all` 并分发其更新后的资源包。仅重载菜单不会让客户端自动加载新图片；ArcMenu 也不会自动发送生成的 ZIP 文件。详见[图片与资源包](/arcmenu-wen-dang/gong-neng-pei-zhi/resource-packs.md)。

### 无法切换鼠标模式

Spigot 不支持鼠标模式。Paper 系服务端需要支持的客户端版本和配套资源包；管理员设置为强制触摸模式时，玩家无法自行切换。检查 `mouse.policy`，并参照[触摸与鼠标输入](/arcmenu-wen-dang/gong-neng-pei-zhi/input-modes.md)操作。

### 占位符没有替换

先区分内置占位符与其他插件提供的占位符。Paper 系服务端使用第三方占位符时，需要 PlaceholderAPI 及提供该占位符的插件或扩展。Spigot 仅支持文档列出的基础占位符。

检查名称、参数和数据键是否正确，确认数据已存在。菜单中的内部占位符不能直接当作其他插件可用的 PlaceholderAPI 占位符。文字更新方式见[占位符与文字格式](/arcmenu-wen-dang/wen-zi-ge-shi/text-placeholders.md)。

### Spigot 配置中没有语言选项

`plugins/ArcMenu/spigot/config.yml` 只设置快捷键。语言选项位于 `plugins/ArcMenu/config.yml`，语言文件位于 `plugins/ArcMenu/languages/`。两类服务端均使用这些语言设置。

客户端语言跟随开启时，修改默认语言不一定改变该玩家的提示。若要统一提示语言，应关闭 `language.follow-player-locale`。菜单文字需在菜单文件中单独修改，详见[语言管理](/arcmenu-wen-dang/gong-neng-pei-zhi/languages.md)。

## 可视化编辑器

### 无法打开编辑器

确认使用 Paper 系服务端，管理员拥有 `arcmenu.admin`，目标菜单已加载，且客户端安装了匹配的 Fabric、Fabric API 和 ArcMenu Editor。更新提示应通过安装兼容编辑器解决。

下载与操作说明见[可视化编辑器](/arcmenu-wen-dang/gong-neng-pei-zhi/editor.md)。同一菜单已有管理员编辑时，需要等待其结束。

### 编辑器拒绝保存

检查提示是否指出菜单文件被外部修改。结束编辑并重新打开最新文件，再重新调整；不要直接覆盖其他管理员的修改。保存失败时也应检查配置错误和文件写入权限。

保存后还需应用或重载才能更新普通玩家使用的菜单。测试按钮动作时，应退出编辑器后正常打开菜单。

## 提交问题时的信息

提供服务端与 Java 版本、玩家客户端版本、使用的功能、复现步骤、相关配置片段和完整报错。涉及图片或编辑器时，还应说明资源包是否已更新、客户端是否安装对应编辑器。

发送配置前移除密码、令牌和私人服务器地址。保留与问题相关的缩进、字段和命令参数，便于复现。