这页的目标是带你 按最短路径跑通一条真实可验证链路：

1. HNCore 共享数据库可用
2. HNMail 能正常启动并建表
3. 管理员或玩家能发一封基础邮件
4. 玩家能打开 /mail 看见邮件
5. 玩家能查看详情、标记已读、删除邮件
6. 如果启用了附件，还能验证领取流程

---

第 0 步：先明确 HNMail 适合做什么

HNMail 当前最适合解决的是：

• 奖励不想直接塞背包，而是先进邮箱
• 玩家不在线，也希望奖励保留到下次上线
• 想统一处理物品、金币、命令类奖励
• 想做欢迎信、补偿信、节日奖励、离线群发

可以把它理解成：

建立在 HNCore 共享数据库与共享消息总线能力之上的邮箱与奖励投递层。

---

第 1 步：准备依赖

必需依赖

• HNCore
• HNMail

可选依赖

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

当前版本最关键的前提不是 Placeholder，而是：

• HNCore 已先启动
• HNCore 的共享数据库已经 active

---

第 2 步：首次启动先确认这些点

启动服务器后，优先确认：

• plugins/HNMail/config.yml 已生成
• plugins/HNMail/messages.yml 已生成
• plugins/HNMail/mail-templates.yml 已生成
• 控制台没有出现“共享数据库不可用”之类的阻断错误

如果你接了 Redis / 共享消息总线，还可以额外确认：

• 同步订阅没有持续报错
• 多服提醒不是必须成功，但最好处于可用状态

这里要区分两类问题：

• 共享数据库不可用：阻断启动
• 共享消息不可用：通常只影响跨服实时提醒

---

第 3 步：先跑通一封最基础的邮件

最稳的第一轮验证，不是模板，也不是群发，而是基础纯文本邮件。

玩家发基础邮件

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

例如：

/mail send Steve 问候|你好，欢迎查看你的第一封邮件

玩家打开邮箱

/mail

你要验证的内容

• 收件箱里确实出现了新邮件
• 打开详情后会标记已读
• 删除后不会再出现在列表中
• /mail unread 的未读统计符合预期

---

第 4 步：再验证附件链路

当基础链路跑通后，再测管理员附件命令。

物品附件

管理员主手拿着物品：

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

如果要发送后扣掉主手物品：

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

金币附件

如果已接 HNEconomy 且开启了 allow-money-attachment：

/hnmail sendmoney <玩家> <货币> <金额> <标题>|<正文>

命令附件

如果开启了 allow-command-attachment：

/hnmail sendcommand <玩家> <标题>|<正文> -- <命令...>

外部物品库附件

如果你计划验证 HNCore 统一物品库网关，也可以补一轮：

/hnmail sendlibitem <玩家> <source:itemId> [数量] -- <标题>|<正文>

这一步更适合放在基础 senditem 已确认没问题之后。 更详细的来源说明与例子，建议直接看 命令说明。

玩家领取

/mail claim <邮件ID>

或者直接在邮件详情 GUI 点击“领取附件”。

你要验证的内容

• 物品附件能正常进入背包
• 背包满时会被拦截，而不是丢物
• 金币附件能正常入账
• 命令附件能按预期执行
• 如果你测试了 sendlibitem，确认外部物品库附件也能正常解析并发送

---

第 5 步：再看模板邮件和群发

当基础链路跑通以后，再去看模板、群发与广播日志会更稳。

你可以先从：

/hnmail sendtemplate <玩家> <模板>

开始。

再继续到：

/hnmail sendtemplateall <模板>
/hnmail sendtemplateall <模板> online

这一步建议放到最后，因为它已经进入“运营投递”层，不再只是基础邮箱验证。

---

第 6 步：学会查群发日志

群发不是黑盒操作。当前版本已经提供：

/hnmail broadcastlog
/hnmail broadcastlog list running
/hnmail broadcastlog list template welcome
/hnmail broadcastlog <任务ID>

建议在测试环境先做一次单发模板、一次在线群发、一次离线群发，然后分别验证：

• 是否生成任务 ID
• 任务是否进入广播日志
• 成功数 / 失败数是否合理
• 失败明细里能否看见原因

---

推荐的首版验证顺序

最建议按下面这个顺序来：

1. 基础邮件
2. 收件箱 GUI
3. 已读 / 删除
4. ITEM 附件
5. 黑名单 / 拒收
6. Redis 新邮件提醒
7. MONEY 附件
8. 模板邮件
9. 群发与广播日志

不要一开始就同时测试所有能力。

否则一旦出问题，你不容易判断是：

• 基础设施层坏了
• 邮件层坏了
• 附件层坏了
• 还是群发与运维层坏了

---

建议联动阅读

跑完第一轮后，建议按下面顺序继续看：

• 想确认依赖和首次启动行为：看 安装与首次启动
• 想调开关和策略：看 config.yml 配置说明
• 想查看命令入口：看 命令说明
• 想理解附件边界：看 邮件投递、附件与领取机制
• 想理解模板、群发与广播日志：看 模板邮件、群发与广播任务
• 想查完整 %hnmail_*% 占位符：看 PlaceholderAPI 占位符

如果你现在的目标是“先把邮箱和奖励投递跑起来”，最稳的路线仍然是：基础邮件 → 物品附件 → 黑名单/拒收 → 再扩模板、群发与广播日志。