HN 系列 Wiki

主题

这页聚焦 HNMail 的实际安装前置条件、首次启动行为与第一次排错重点。

依赖关系 ​

必需依赖 ​

  • HNCore
  • HNMail

可选依赖 ​

  • HNEconomy：启用金币附件时需要
  • PlaceholderAPI：启用 %hnmail_*% 占位符时需要

当前版本里，HNMail 强依赖 HNCore 的共享数据库。

也就是说，最先要确认的不是 GUI，而是：

  • HNCore 已安装并先于 HNMail 启动
  • HNCore 的共享数据库已经可用

安装顺序建议 ​

最稳的安装顺序是：

  1. 先安装并验证 HNCore
  2. 再放入 HNMail
  3. 如果需要金币附件，再安装 HNEconomy
  4. 如果需要占位符展示，再安装 PlaceholderAPI

建议不要一开始就把所有外围能力一起接上。先把基础邮箱链路跑通，后续排错会轻松很多。

如果你计划使用 /hnmail sendlibitem，还要额外确认 HNCore 统一物品库网关已经可用；不同物品库来源名可能会被归一化到同一个 canonical source。

首次启动时会发生什么 ​

HNMail 首次启动时大致会做这些事：

  • 加载 config.yml
  • 加载 messages.yml
  • 加载 mail-templates.yml
  • 检查 HNCore 共享数据库是否可用
  • 自动创建邮箱相关数据表与索引
  • 初始化命令、GUI、服务层
  • 尝试订阅共享消息总线
  • 如果启用了清理任务，则启动周期清理
  • 如果安装了 PlaceholderAPI 且配置允许，则注册 %hnmail_*% 占位符

首次启动后建议检查的文件 ​

至少确认这些文件已经生成：

  • plugins/HNMail/config.yml
  • plugins/HNMail/messages.yml
  • plugins/HNMail/mail-templates.yml

其中：

  • config.yml：功能开关、同步、清理、附件能力
  • messages.yml：提示文本与广播日志文案
  • mail-templates.yml：模板邮件与模板附件

首次启动后建议检查的数据库表 ​

当前版本通常至少会出现：

  • hnmail_mail
  • hnmail_attachment
  • hnmail_player_settings
  • hnmail_block_list
  • hnmail_audit
  • hnmail_player_registry
  • hnmail_broadcast_job
  • hnmail_broadcast_item

如果这些表没有创建出来，优先看：

  • HNCore 的共享数据库有没有 active
  • 表前缀是否冲突
  • 启动日志里有没有 SQL 初始化报错

首次启动后最该看哪些日志 ​

正常但重要的日志 ​

  • 插件已启用
  • HNMail 已加载完成，模板数量=...
  • 如果 PlaceholderAPI 可用，看到已注册占位符相关信息
  • 如果有自动清理，后续看到清理完成日志

需要重点关注的异常日志 ​

  • 共享数据库不可用
  • 建表失败
  • 配置文件加载失败
  • 同步订阅失败
  • HNEconomy 不可用（如果你打算用金币附件）

注意：

  • 共享数据库不可用 通常是阻断型问题
  • 共享消息不可用 通常只影响跨服实时提醒

第一次验证建议做什么 ​

建议按下面这组最小步骤验证：

1. 发一封基础邮件 ​

text
/mail send <玩家> <标题>|<正文>

2. 打开收件箱 ​

text
/mail

3. 看详情并删除 ​

确认：

  • 邮件能显示
  • 点进详情能正常标记已读
  • 删除后不再显示在列表中

4. 如果你开了物品附件，再测一封 senditem ​

text
/hnmail senditem <玩家> <标题>|<正文>

HNEconomy 什么时候再接更合适 ​

如果你当前目标只是“把邮箱跑起来”，建议先不要急着开金币附件。

更稳的顺序是：

  1. 先跑通基础邮件
  2. 再跑通物品附件
  3. 再接 HNEconomy
  4. 最后再启用 allow-money-attachment

这样一旦金币附件领取失败，你能更快判断问题是在：

  • HNMail 的附件逻辑
  • 还是 HNEconomy 的货币与账务配置

PlaceholderAPI 什么时候再接更合适 ​

同样建议在基础邮件跑通后再接。

因为 %hnmail_unread%、%hnmail_latest_broadcast_status_text% 这些占位符属于展示层增强，不是邮箱的基础链路。

如果首次启动失败，先看哪里 ​

优先按这个顺序排：

  1. HNCore 是否真的启用了共享数据库
  2. HNMail 的配置文件是否生成完整
  3. 表前缀是否与已有表冲突
  4. 同步报错是否只是提醒层异常
  5. 如果是金币附件场景，再看 HNEconomy 是否真正可用

建议联动阅读 ​

HN 系列插件文档

Copyright © 2024