常见问题与排错
适用版本 1.0.0 ｜ 后台路径：无
按「现象 → 原因 → 处理」组织。排查前先做两件事：强刷页面、确认插件处于启用状态。
安装与访问
访问 /reward 提示 404
- 「插件 → 打赏插件 → 设置 → 基础设置」里的「启用打赏页面」是否被关闭；
- 站点是否已存在占用
/reward路径的自定义页面，需要改掉该页面的固定链接； - 主题是否提供
layout契约（html (head, content)），未提供时页面无法套用主题外壳。
页面能打开，但没有站点的页头页脚
主题未实现 layout 页面布局契约（Halo 2.26.0+）。升级主题或改用支持该契约的主题；页面内容本身不受影响。
关闭「启用打赏页面」后，赞助者墙与统计接口还能访问
该开关只控制 /reward 页面、配置读取、验证码与提交入口。/public/wall、/public/stats 是独立的只读接口，方便主题在其它页面展示数据；需要连墙面一起下线时，关闭「展示赞助者墙」；统计接口没有关闭开关，不要在主题中调用即可。
前台与提交
弹窗不显示或提交一直失败
- 站点在 CDN / WAF 之后时，确认
/apis/api.reward.nanzhiy.cn/**与/plugins/plugin-reward/assets/**未被拦截； - 提交接口每 IP 10 分钟 5 次、验证码每 IP 1 分钟 10 张，触发后页面会提示「提交过于频繁」，稍等即可；
- 开启「提交时校验图形验证码」时必须填写图形验证码，验证码 5 分钟过期、一次性使用。
验证码总是提示错误 验证码点图可换一张，提交时以当前图片里的字符为准。站点在反向代理后时，还要确认代理透传了真实来源 IP。
赞助者墙不显示某条记录 只有「已确认」的记录才会上墙，「待确认」需要在后台确认；「展示赞助者墙」与「在赞助者墙显示金额」两个开关分别控制整面墙与金额显示。
访客填写的头像不显示
头像地址只接受 http(s) 或站内路径，且需要开启「允许访客填写头像地址」；地址失效或防盗链时，赞助者墙会显示昵称首字占位。
留言 / 交易单号 / 头像框没有出现 这些字段跟随「记录与展示」里的开关显示，主题不需要另做判断；开启后前台表单会自动出现对应输入框。
爱发电
爱发电订单没有自动入库
- 爱发电开发者后台的 Webhook 地址要填
https://你的域名/apis/api.reward.nanzhiy.cn/v1alpha1/afdian/webhook； - 插件设置里必须启用爱发电并配置含
token键的凭据，否则回调会被安全校验拦下； - 站点若前置了 CDN / WAF，需把该路径加入白名单；
- 平台收到成功响应后不会重推，漏掉的订单在「内容 → 打赏」点「同步爱发电」补齐。
同一条订单出现了两条记录
正常不会发生：记录以 afdian-{订单号} 命名，重复推送会命中同一条。若确实出现，请带上订单号反馈。
订单昵称显示为「匿名读者」 爱发电的赞助者查询失败或未返回昵称时会回退为「匿名读者」，头像留空；可在后台手动编辑记录补充昵称。
数据与隐私
卸载插件会删除打赏记录吗
不会。记录保存在 Halo 扩展存储的自定义模型 RewardRecord 中，重新安装后可继续访问。需要彻底清理时，请在卸载前于「内容 → 打赏」删除。
联系方式和交易单号会公开吗 不会。两者只在后台可见，任何匿名接口都不返回；赞助者墙只展示昵称、头像、留言、金额与日期。
插件会采集访客 IP 吗 不会。提交接口只在内存里按来源 IP 做短时频率限制，不落库、不写日志；限流是单实例实现，重启即失效。
统计金额可以隐藏吗
「在赞助者墙显示金额」只控制墙面的金额显示。/public/stats 会返回已确认记录的累计笔数与金额，匿名可访问且没有关闭开关；不需要公开收入数据时，不要在主题里调用它。
CSV 打开后单元格变成了公式
插件已对以 = + - @ 开头的内容做转义；若仍遇到，请带上具体内容反馈。
如何反馈
提 Issue 时请附上：
- Halo 版本、打赏插件版本、主题与版本
- 复现步骤（哪个页面、点了什么、期望结果）
- 相关报错日志或截图，涉及爱发电时附订单号与回调时间
Issue 地址：https://github.com/AloneNanNan/halo-plugin-reward/issues