主题
这页汇总 HNMail 当前版本最常见的排错点。
插件启动时报“共享数据库不可用”
先检查：
HNCore是否已先于HNMail启动HNCore的共享数据库是否已经 active- 当前环境是否真的允许 HNMail 访问共享数据库
这是阻断型问题。数据库不可用时，HNMail 不会正常工作。
Redis / 同步订阅报错，但邮箱还能用
这通常意味着：
- 邮件主数据仍然能走共享数据库
- 但跨服实时提醒可能失效
也就是说，问题通常在“提醒层”，不一定在“主业务层”。
/mail send 发不出去
优先检查：
mail.allow-player-send是否开启- 目标玩家是否有效
- 玩家是否在对方黑名单中
- 对方是否关闭了玩家来信
- 标题 / 正文是否为空
/mail 打开后看不到邮件
先确认：
- 邮件是否真的发送成功
- 目标 UUID 是否正确
- 邮件是否已经被删除
- 邮件是否已过期
如果是跨服环境，还要区分：
- 数据没写入数据库
- 还是数据已写入，但只是提醒没有同步
附件领取失败怎么办
物品附件
先看：
- 背包是否已满
- 物品数据是否序列化正常
金币附件
先看：
- 是否安装了
HNEconomy allow-money-attachment是否为true- 货币 ID 是否存在
- 金额是否超出最大余额限制
命令附件
先看：
allow-command-attachment是否为true- 命令内容是否为空
- 命令本身是否能在后台正常执行
模板找不到
优先检查：
mail-templates.yml里是否真的存在该模板 key- 模板 key 是否大小写写错
- 模板标题
title是否为空 - 重载后模板数量是否正常
当前模板加载时会把 key 转成小写，建议你自己写模板时也统一用小写。
群发为什么要单独做任务日志？
因为“全服群发”不是一次普通点按，而是一个后台任务。
运营最常关心的是：
- 谁发的
- 发的哪个模板
- 发给了多少人
- 成功多少，失败多少
- 哪些目标失败了
所以群发日志是必要的，不是附属功能。
/hnmail broadcastlog 应该怎么用
当前常见用法：
text
/hnmail broadcastlog
/hnmail broadcastlog list running
/hnmail broadcastlog list template welcome
/hnmail broadcastlog list completed template compensation 2
/hnmail broadcastlog <任务ID>它可以帮你看：
- 最近任务列表
- 按状态筛选
- 按模板筛选
- 单个任务详情与失败明细
/hnmail sendlibitem 发送失败怎么办
优先检查：
source:itemId格式是否正确- 来源名是否写错
- 当前服务器上的 HNCore 统一物品库网关是否可用
- 对应来源当前是否可用
itemId是否真实存在- 数量是否为大于 0 的正整数
如果你看到的是“来源不可用”之类的提示，问题通常不在邮箱系统本身，而在：
- HNCore 统一物品库门面未就绪
- 对应物品库插件未安装
- 该来源在当前环境未注册成功
如果你看到的是“唯一堆叠不支持”之类的提示，说明当前解析结果不适合被安全序列化为邮件附件。
为什么某些 sendlibitem 来源别名不会出现在补全里，但手动输入后仍可能可用
这是当前实现的正常现象。
原因是：
- 命令补全只会优先提示一组已知来源前缀
- 实际执行时，来源名还会经过 HNCore 统一物品库网关做 canonical source 归一化
所以会出现两种情况：
- 某个来源别名没有出现在 TAB 补全里
- 但你手动输入后，网关仍然能把它识别并归一化到正确来源
如果手输后能成功发送，说明问题只是“补全未展示”，不是“命令不支持”。
PlaceholderAPI 没返回值
先检查：
PlaceholderAPI是否已安装placeholder-api.enabled是否为true- HNMail 是否成功注册扩展
- 占位符是否写对
当前常见占位符：
%hnmail_unread%%hnmail_total%%hnmail_allow_player_mail_text%%hnmail_broadcast_job_count%%hnmail_latest_broadcast_status_text%%hnmail_latest_broadcast_success_rate_text%
如果插件本体功能正常，只是占位符没值，优先排查挂钩与注册，而不是先怀疑邮箱主逻辑。
另外要注意，HNMail 当前对占位符查询做了极短时间缓存。 如果你刚完成发信、已读、领取、删除等操作，占位符值可能会有大约 1 秒内的短暂延迟，这通常不是异常。
管理员最常用的排错命令有哪些
推荐优先掌握：
text
/hnmail reload
/hnmail cleanup
/hnmail broadcastlog
/hnmail broadcastlog <任务ID>再加上一些基础验证命令：
text
/mail unread
/mail claim <邮件ID>
/hnmail sendtemplate <玩家> <模板>这几条已经能覆盖大部分：
- 配置重载
- 数据清理
- 群发任务排查
- 附件领取验证
- 模板发送验证
如果我是第一次上线 HNMail，最稳的方式是什么？
建议顺序：
- 只开基础邮件
- 先跑通收件箱与详情
- 再开
ITEM附件 - 再开黑名单 / 拒收 / 提醒
- 最后再接金币、命令、模板、群发
不要一开始就把所有开关全打开。
这样一旦出问题，你能很快判断是在：
- 基础设施层
- 邮件层
- 附件层
- 模板层
- 群发层
建议联动阅读
- 想重跑最小验证：看 快速开始
- 想核对配置：看 config.yml 配置说明
- 想理解附件与领取：看 邮件投递、附件与领取机制
- 想理解模板、群发与广播日志：看 模板邮件、群发与广播任务
- 想了解插件接入：看 集成与 API
- 想查完整
%hnmail_*%占位符：看 PlaceholderAPI 占位符