HNCore 迁移指南

版本信息

• 当前版本: 3.0.5
• 上一主要版本: 2.3.0
• 破坏性变更: v3.0.0 包含破坏性变更

---

⚠️ v3.0.0 破坏性变更

最低版本要求

• Minecraft 版本：1.20.1+（不再支持 1.20.1 以下版本）
• 服务端类型：Paper 或兼容服务端
• Java 版本：17+

移除的 API

1. TaskUtil 工具类

旧代码（已失效）：

TaskUtil.runTask(plugin, () -> {
    // 任务逻辑
});

TaskUtil.runTaskLater(plugin, () -> {
    // 延迟任务
}, 20L);

新代码：

HNCoreAPI.getScheduler().runTask(() -> {
    // 任务逻辑
});

HNCoreAPI.getScheduler().runTaskLater(() -> {
    // 延迟任务
}, 20L);

2. MessageManager 实现类

旧代码（已失效）：

MessageService messageService = HNCoreAPI.getMessageService(plugin);
String message = messageService.getMessage("path.to.message");

新代码：

MessageFacade messageFacade = HNCoreAPI.getMessageFacade();
String message = messageFacade.render("path.to.message", PlaceholderContext.create());

临时兼容方案（不推荐）：

// MessageServiceAdapter 提供临时兼容，但已标记为待删除
MessageService messageService = HNCoreAPI.getMessageService(plugin);

3. ItemMeta 旧 API

旧代码（不再支持）：

String displayName = meta.getDisplayName();
List<String> lore = meta.getLore();

新代码（1.20.1+ Component API）：

Component displayName = meta.displayName();
List<Component> lore = meta.lore();

// 如果需要转换为字符串
String displayNameStr = LegacyComponentSerializer.legacySection().serialize(displayName);

详细迁移指南

请查看 v3.0.0 更新日志 获取完整的迁移指南。

---

这份迁移指南真正该看什么

这页只保留升级时必须知道的内容，不再重复完整教程。

你正在从 2.x 升到 3.x

优先看：

1. v3.0.0 - 移除过时 API，修复脚本系统
2. 本页前半部分的破坏性变更说明
3. 开发者 API 与集成指南

你正在补看 2.2.0 / 2.3.0 这轮新增能力

请直接看：

• 搜索与多渠道输入框架
• v2.3.0 - 完善多渠道输入框架

你只是想确认依赖方式有没有变化

请直接看：

• hncore-api 与运行时依赖说明

---

升级检查清单

服主侧

• 确认服务端满足 Paper / 1.20.1+ / Java 17+ 确认服务端满足 **Paper / 1.20.1+ / Java 17+**
• 阅读目标版本更新日志
• 升级前备份 config.yml、storage.yml、 升级前备份 `config.yml`、`storage.yml`、`auth.yml`
• 升级后执行 /hncore status 与 /hncore reload 升级后执行 `/hncore status` 与 `/hncore reload` 做基础验证
• 如果使用脚本功能，执行 /hncore scripts list 和 /hncore scripts enabled 如果使用脚本功能，执行 `/hncore scripts list` 和 `/hncore scripts enabled` 检查状态

二开作者侧

• 检查是否仍在使用已移除 API
• 检查是否还在直接依赖运行时实现类
• 确认开发依赖已切到 确认开发依赖已切到 `hncore-api`
• 检查是否存在 reload 后缓存失效风险
• 回归测试消息、调度、共享存储、ClusterBus、输入框架等关键能力

---

升级后建议继续阅读

• 配置有疑问：看 config.yml 配置说明、storage.yml 配置说明、auth.yml 配置说明
• 运行状态有疑问：看 命令说明、常见问题
• 二开接入有疑问：看 开发者 API 与集成指南、HNCore Java API
• 搜索 / 输入相关能力：看 搜索与多渠道输入框架

---

一句话：这页负责“怎么安全升级”，详细能力说明已经拆回各自专题页，不再在这里重复。