服务端安装指南 ​

ChaUI 的服务端部分负责管理页面、保存编辑器内容、打开或关闭页面，以及处理需要由服务器确认的交互。大部分目录和文件都会在插件首次正常启动后自动生成，安装时不需要提前手工创建。

安装前准备 ​

安装前请确认服务器满足以下条件：

• 使用 Minecraft 1.20.1、1.21.1、1.21.4、1.21.8、1.21.11 或 26.2。
• 服务端为对应版本的 Spigot 或 Paper；其他服务端核心请先确认兼容情况。
• Minecraft 1.20.1 服务端使用 Java 17，Minecraft 1.21.x 使用 Java 21，Minecraft 26.2 使用 Java 25。
• 已安装与当前服务器环境匹配的 ChaCore。
• 已准备 ChaUI-1.3.3.jar；所有正式支持的服务端版本共用这一个插件文件。

安装插件 ​

1. 完全关闭服务器。
2. 将 ChaCore 与 ChaUI 的插件文件放入服务器的 plugins/ 目录。
3. 启动服务器并等待插件加载完成。
4. 查看控制台，确认 ChaCore 与 ChaUI 均已正常启用，且没有缺少前置或 Java 版本错误。

安装前的目录大致如下：

服务器目录/
└─ plugins/
   ├─ ChaCore.jar
   └─ ChaUI.jar

实际文件名可能带有版本号，只要确认放入的是与当前服务端匹配的正式文件即可。

首次启动会自动完成什么 ​

ChaUI 首次正常启动后，会在 plugins/ChaUI/ 下准备运行所需的默认文件，并释放内置示例页面。正常使用时不需要自己生产配置文件、语言文件或示例页面，也不需要提前建立页面目录。

config.yml 已提供适合直接使用的默认设置，大多数服务器无需修改。之后通过游戏内编辑器创建并保存页面时，ChaUI 也会负责生成对应的页面文件；覆盖已有页面前，旧文件会自动进入备份目录。

安装后的目录结构 ​

首次启动并完成一次页面保存后，常见结构如下：

服务器目录/
└─ plugins/
   ├─ ChaCore.jar
   ├─ ChaUI.jar
   └─ ChaUI/
      ├─ config.yml
      ├─ lang.yml
      ├─ pages/
      │  ├─ hud_health_demo.yml
      │  ├─ chaui_feature_layout_demo.yml
      │  ├─ first_chest_replacement.yml
      │  ├─ 你的页面.yml
      │  └─ 菜单/
      │     └─ shop.yml
      └─ backups/
         └─ pages/
            └─ 页面ID-保存时间.yml

备份目录会在需要保存旧页面备份时出现。如果服务器刚安装、还没有覆盖保存过页面，看不到该目录属于正常情况。

用子目录整理页面 ​

pages/ 支持子目录，最大深度 16。它适合把商店、副本、HUD 等页面分类收纳。子目录只用于整理文件，不会成为页面 ID 的一部分。例如 pages/菜单/shop.yml 的页面 ID 仍然是 shop，打开时不要填写 菜单/shop。

使用时请遵守以下规则：

• yml 文件名必须与根级 id 完全相同，例如 shop.yml 对应 id: shop。
• 页面 ID 在整棵 pages/ 目录中全局唯一。如果两个不同子目录声明了同一 ID，这个 ID 对应的冲突文件会全部拒绝加载。
• 编辑器再次保存已有页面时，会写回原位置；备份也会保留相同目录结构。
• 新建页面默认保存到 pages/ 根目录，之后可在服务器关闭时手动移入子目录。
• 为避免读取到目录外的文件，符号链接文件和符号链接目录会被跳过。

第三方插件如果想自带页面，请使用页面注册 API，不要直接写入 ChaUI 的数据目录。

文件与目录介绍 ​

页面图片与音效不放在服务端的 plugins/ChaUI/ 目录中。它们属于客户端本地素材，应按照客户端安装指南放入每位玩家的 ChaUI 资源目录。

如何确认安装成功 ​

可以按以下顺序检查：

1. 控制台中 ChaCore 与 ChaUI 均显示为正常启用。
2. plugins/ChaUI/ 已自动出现。
3. pages/ 中可以看到三个内置示例页面。
4. 安装客户端 Mod 的管理员进入服务器后，可以正常打开 ChaUI 编辑器或示例页面。
5. 保存一个测试页面后，pages/ 中出现对应的 yml 文件。

如果前三项正常，但客户端无法打开页面，请继续检查客户端 Minecraft 版本、加载器和 ChaUIMod 是否与服务端对应。Forge 1.20.1 必须使用 47.4.10 至 47.4.x；1.21.x 请使用对应版本的 NeoForge 或文档中标为支持的 Fabric 版本；26.2 客户端还必须选择 OpenGL 图形后端。

更新 ChaUI ​

更新前建议先停止服务器，并备份整个 plugins/ChaUI/ 目录。随后替换 plugins/ 中的 ChaUI 插件文件并重新启动服务器。

不要删除 pages/，其中包含已经制作的页面。一般也不需要删除 config.yml 或 lang.yml；如果新版本需要新增默认内容，插件会按其更新方式处理。

服务端插件与客户端 Mod 应尽量同步更新，避免双端功能或页面格式不一致。

常见问题 ​

启动时提示缺少前置 ​

确认 ChaCore 已放入 plugins/，并且版本适用于当前服务器。修正后完整重启服务器。

没有生成 ChaUI 文件夹 ​

先检查控制台中的 ChaUI 启动错误。常见原因包括 Java 版本不正确、ChaCore 未安装或插件文件与服务器版本不匹配。只有插件正常启用后，默认文件才会生成。

没有看到备份目录 ​

备份目录在页面发生覆盖保存时才需要使用。新安装且尚未覆盖过页面时，没有备份文件属于正常情况。

页面能打开，但图片或音效缺失 ​

图片和音效来自客户端本地资源，不会由服务端插件自动发送。请检查客户端的 resourcepacks/ChaUI/ 目录，并确保所有玩家获得了相同素材。

是否需要自己编写页面 yml ​

不需要。推荐直接使用游戏内编辑器创建和保存页面，ChaUI 会自动生成对应文件。页面 yml 主要用于备份、迁移和高级维护。