下载与安装
环境要求
注意
请不要热加载插件。首次启动或切换数据库类型时，插件可能联网下载运行库。
| 项目 | 要求 |
|---|---|
| Java | Java 8 或以上 |
| 服务端 | Spigot API 1.8 或以上，以及 Paper/Purpur 等下游服务端 |
| 当前源码版本 | 2.4.12 |
1.7.10 仅 legacy 分支有部分支持：2.4.0-legacy。
Paper/Purpur 不是必需项，但在 Paper 或下游服务端上会额外启用装备穿戴检测，auto-bind.onEquipWear 和 auto-unbind.onEquipWear 才有意义。
插件依赖
必装
| 插件 | 作用 | 下载 |
|---|---|---|
| NBTAPI | 读写物品 NBT，SakuraBind 硬依赖 | GitHub / Modrinth / Spigot |
按需安装的软依赖
| 插件 | 作用 | 下载 |
|---|---|---|
| PlaceholderAPI | 注册占位符，解析消息、lore、暂存箱标题中的变量 | GitHub / Spigot |
| AuthMe | 登录兼容；迁移模块强制绑定时可通过 AuthMe 查找 UUID | GitHub / Spigot |
| MMOItems | 匹配 MMOItems 物品，并在掉落表生成物品时自动绑定 | GitLab / Spigot |
| ItemsAdder | settings.yml 中匹配 ItemsAdder 物品 | Wiki / Spigot |
| NeigeItems | 匹配 NeigeItems 物品，并在给予单个物品或物品包时自动绑定 | GitHub |
| MythicMobs | 匹配 MythicMobs 物品，并在 MythicMob 死亡掉落时自动绑定；当前按 5.1.2 API 编译 | 官网 |
| Oraxen | settings.yml 中匹配 Oraxen 物品 | 官网 / GitHub / Polymart / Spigot |
| GermPlugin | 扫描萌芽槽位物品 | 官网 |
| BanItem | 扫描部分 Mod 背包槽位 | Gitee |
| mcMMO | 禁止绑定物品被分解、修复、缴械 | 官网 / GitHub / Spigot |
| GlobalMarketPlus | 将送回物品发送到全球市场邮箱 | Gitee |
| SweetMail | 将送回物品发送到 SweetMail 邮件 | GitHub |
| PlayerDataSQL | 玩家数据同步兼容 | GitHub |
| InvSync | 玩家数据同步兼容 | 官网 |
| HuskSync | 玩家数据同步兼容 | GitHub / Spigot |
下载
- GitHub Releases: https://github.com/SakuraTown/SakuraBind/releases
- GitHub Actions 预览版: https://github.com/SakuraTown/SakuraBind/actions
- 蓝奏: https://iseason.lanzoub.com/b00qhdv2f ，密码
69zm - QQ 群
887296263群文件
安装
- 关闭服务端。
- 安装必需依赖
NBTAPI，并按需安装软依赖插件。 - 将
SakuraBind.jar放入服务端根目录/plugins/。 - 启动服务端，等待运行库下载、数据库连接和配置生成完成。
- 关闭服务端，备份并编辑
plugins/SakuraBind/下的配置文件。 - 再次启动服务端，确认控制台没有依赖、数据库或 YAML 解析报错。
开启或关闭 block-listener、entity-listener、模块总开关、日志文件路径等重启生效项后，需要重启服务端。
离线服务器
插件会在首次启动和切换数据库类型时下载 Kotlin、Exposed、HikariCP、数据库驱动等运行库，默认放在服务端根目录的 libraries。如果服务器不能访问 Maven 仓库，请先在网络正常的同版本测试环境启动一次，再复制 libraries 目录到正式服。
安装后检查
启动后检查控制台：
- 没有
NBTAPI缺失报错。 - 没有数据库连接失败报错。
- 出现
SakuraBind启用成功日志。 plugins/SakuraBind目录已经生成配置文件。- 默认 H2 数据库文件
plugins/SakuraBind/database/database_sakurabind.mv.db可正常创建。
进入游戏后执行：
/sakurabind
如果能看到子命令列表，说明命令已注册。
再执行：
/sakurabind getLost
普通玩家默认应能使用该命令。若提示没有权限，请检查权限插件是否覆盖了默认权限。
第一次配置建议
新服建议按下面顺序逐步启用，不要一次打开所有模块：
| 步骤 | 操作 | 验证 |
|---|---|---|
| 1 | 保持默认，只测试物品绑定 | /sakurabind bind item <玩家> |
| 2 | 配置 settings.yml 自动绑定规则 | 用非 OP 玩家测试点击或扫描触发 |
| 3 | 按需开启 block-listener 或 entity-listener | 重启后再测试方块/实体命令 |
| 4 | 按需开启绑定道具、迁移、唯一物品等模块 | 先在测试服或少量物品上验证 |
settings.yml 默认带有 example 演示匹配器。正式使用前建议删除、注释或改成自己的匹配器，避免示例规则误命中真实物品。
默认全局设置会禁止绑定物品参与合成：
global-setting.yml
item-deny:
craft: true
如果你的玩法允许绑定物品合成，需要明确改成 false，或只在特定 settings.yml 匹配器中覆盖。