小程序消息推送配置排错教程｜服务器回调、Token 校验与重试幂等 – MPForge

一、排错顺序：从 URL 可达开始，一层一层往下

结论先记住：推送排错最忌讳乱改配置——四层顺序查完，问题基本都能定位到某一层。

回调验证不过、消息收不到，症状相似但根因不同。把下面这张表当检查表用：

开发先拿 curl 或抓包工具确认 URL 从公网可达且返回 200，再逐层往下；商家侧只需要记住：回调地址必须是 https，http 开头的地址连验证这关都过不了。

二、开工前备齐四样材料

材料不齐就开查，往往查一半发现根本没备份，改坏了回不去。

• 服务器配置截图：后台 URL、Token、消息加解密方式三项目前状态，改动前先存档，改坏能对回去。
• 公网 HTTPS 环境：有效证书、稳定域名，域名归属与校验文件口径见 小程序域名校验文件配置，服务器域名整体要求见 小程序服务器域名配置。
• Token/AESKey 保管：只存服务端配置中心，禁止写进前端代码、聊天记录或共享文档。
• 重试日志：记录每次投递的消息标识、响应码与处理结果，排重试问题时这是唯一证据。

三、落地步骤：从验证到压测

顺序不能乱：先让验证通过，再谈业务处理。按这五步走：

1. 校验 URL 与证书：确认公网可达、证书在有效期内、响应在超时窗口内返回 echostr，验证逻辑不掺杂任何业务处理。
2. 核对 Token：后台配置与代码里的 Token 完全一致，签名校验按官方算法逐字符实现，不自己发明简写。
3. 处理重试幂等：用消息标识做幂等键，先查处理记录再执行业务，重复投递直接返回上次结果。
4. 区分订阅消息与推送配置：服务器推送是平台向你回调，订阅消息是用户授权后你主动下发，两套东西别混排错，授权体验见 小程序订阅消息授权设计，两者差异见 小程序订阅消息与模板消息对比。
5. 压测异常包：用畸形报文、慢响应、大消息体三类异常包压一遍接口，确认不会拖垮服务或被绕过验签。

四、重试与幂等：防住重复业务

结论：平台对未及时响应的回调会重试，没有幂等设计，重复发货、重复扣库存是必然结果。

• 响应要快：回调先落库再异步处理，5 秒内返回成功；把业务逻辑全塞在响应前，超时重试就来了。
• 幂等键选对：用平台消息标识做唯一键，别用订单号自加时间戳这种会变的字段。
• 失败要分型：参数错误重试也没用，直接告警；网络抖动类失败才进入重试队列，重试策略参考 小程序请求重试策略。
• 对账兜底：每天用重试日志对一次账，发现有消息始终未成功，人工介入补处理。

五、线上翻车点

结论：这类故障的翻车点不在功能，而在安全与重复，三条红线别碰。

• HTTP 回调：明文传输可被截获篡改，必须全程 HTTPS。
• 回调不验签：任何人 POST 一段报文就能伪造用户消息，验签是第一道门，加解密实现可参考 小程序加密解密接口注意事项。
• 重试导致重复业务：发货、通知、积分发放全靠回调触发时，幂等缺失就是资损，先补幂等再补功能。

订阅消息的频控与发送侧问题另按 推送频率限制应对 的口径处理，别和服务器回调排错混在一起查。

六、避坑清单

这三条坑都和「想当然」有关：以为响应了就成功、以为没人会伪造、以为重试无害。

• 别在验证接口里夹业务：echostr 校验必须纯净，业务代码混进去会让验证随机失败。
• 别跳过验签直接处理：验签成本极低，省掉它等于把用户消息入口暴露给公网。
• 别假设只投一次：按「一定会重试」设计幂等，上线后就不会被重复消息打脸。
• 别把推送配置当订阅消息调：收不到订阅消息去查服务器配置是白费功夫，两套链路先分清。

七、常见问题 FAQ