微信小程序的“消息推送”功能，可能是很多开发者又爱又恨的一个模块。爱它，是因为它能帮你召回用户、提升活跃度；恨它，是因为稍有不慎就容易踩坑，比如用户收不到消息、模板审核被拒、或者因为格式问题被平台警告。今天这篇文章，我打算把这块内容掰开揉碎了讲，不仅讲怎么配置、怎么写代码，还会结合我实际遇到过的问题，帮你绕过那些文档里没写的“暗礁”。

一、消息推送的核心逻辑：别把“订阅”当成“发送许可”

很多新手容易犯的第一个错误：以为用户点了“订阅”按钮，我就能随时随地给他发消息了。实际上，微信小程序的订阅消息分两种——一次性订阅和长期订阅（仅限特定行业）。一次性订阅的意思是：用户每次授权，你只能给他发一条消息。发完这条，授权就失效了，下次再想发，得让用户重新订阅。

举个例子：你做了一个课程预约小程序。用户预约了一门课，你希望在上课前30分钟提醒他。这时候，用户在预约页面点了“订阅”按钮，你拿到这个授权，只能发一条关于“上课提醒”的消息。如果用户又预约了另一门课，你还需要他再次点击订阅。这个机制的本质，其实是微信在保护用户不被过度骚扰。理解了这个前提，你才能正确设计你的订阅流程——别指望一次订阅能搞定所有推送。

二、模板的选用与审核：这里有个容易忽略的“潜规则”

微信提供了很多官方模板，但你会发现，有时候你申请的模板审核不通过。原因往往不是你的文案有问题，而是模板的使用场景和你的小程序类目不匹配。比如你的小程序属于“教育”类目，但你申请了一个“快递通知”的模板，哪怕文案写得再好，审核也会驳回。因为微信会校验你的小程序主体资质和模板的关联性。

解决这个问题的思路有两个：

1. 优先在官方模板库中搜索与你业务场景关键词匹配的模板。比如“预约成功通知”、“订单支付成功”这类，几乎覆盖了大多数场景。

2. 如果找不到完全匹配的，可以尝试申请自定义模板。但自定义模板的审核会更严格，你需要提供详细的业务说明，甚至附上用户使用场景的截图。我见过一个比较聪明的做法：某健身小程序申请“训练计划提醒”模板时，在说明里写清楚了用户会在什么时间、因为什么原因收到这条消息，并附上了用户授权页面的截图，这样审核通过率会高很多。

三、代码实现中的“隐形陷阱”：别让消息发不出去

代码层面的坑，我总结为三个最常见的“死法”：

死法一：access_token过期。每次调用发送接口都需要access_token，但它的有效期只有7200秒。在代码里只拿一次token，然后反复使用，两小时后就会报错。正确的做法是：每次发送前检查token是否过期，或者用一个定时任务去刷新token。我习惯的做法是：把token和它的过期时间存到Redis或本地缓存里，每次发送前先判断是否过期，如果过期就重新获取。

死法二：模板ID填错了。这个听起来很蠢，但确实经常发生。尤其是当你从微信公众平台复制模板ID时，很容易多复制一个空格或者漏掉一个字符。建议在代码里把模板ID写成一个常量，并且每次发布前用测试环境跑一遍。

死法三：用户拒绝了订阅。当用户点击“订阅”时，如果他在弹出的授权框中选择了“拒绝”，你的代码仍然会走成功的回调，但实际并没有拿到授权。这时候如果你直接调用发送接口，会收到一个“用户拒绝授权”的错误。所以，在用户点击订阅按钮后，一定要判断wx.requestSubscribeMessage的回调结果里，每个模板ID对应的授权状态。只有状态是“accept”时，才去存储这个授权。

四、实战步骤：从用户授权到消息发送，完整走一遍

假设你现在要做一个“订单发货提醒”的功能，用户下单后，商家发货时，自动给用户发一条消息。具体操作如下：

第一步：在微信公众平台申请模板

登录小程序后台，进入“功能-订阅消息-公共模板库”，搜索“订单发货通知”。选一个包含“订单编号”、“商品名称”、“物流公司”和“物流单号”这四个字段的模板。复制模板ID，注意不要复制多余的空格。

第二步：前端代码，让用户授权

在用户下单成功后的页面，弹出一个按钮，比如“开启发货提醒”。点击按钮时，调用以下代码：

wx.requestSubscribeMessage({

tmplIds: ['你的模板ID'],

success(res) {

if (res['你的模板ID'] === 'accept') {

// 用户同意了，把用户的openid和模板ID存到你的数据库

// 注意：这里只存openid和授权状态，不要存任何用户敏感信息

} else {

// 用户拒绝了，可以提示“您将无法收到发货通知”

}

},

fail(err) {

// 调用失败，可能是用户网络问题，建议重试

}

})

第三步：后端代码，发送消息

当商家在后台点击“发货”按钮时，你的后端需要做两件事：

1. 从数据库里查出这个用户的openid和之前存储的模板ID。

2. 调用微信的发送接口：

POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=你的token

请求体示例：

{

"touser": "用户的openid",

"template_id": "你的模板ID",

"page": "pages/orderDetail/orderDetail?orderId=123",

"data": {

"thing1": { "value": "2024年新款运动鞋" },

"character_string2": { "value": "DD20241001" },

"thing3": { "value": "顺丰快递" },

"character_string4": { "value": "SF1234567890" }

}

}

注意：data字段里的key（比如thing1、character_string2）必须和模板里定义的字段名完全一致。如果你不确定，可以在模板详情里查看“字段名称”那一列。另外，每个字段的value不能超过20个字符，否则会发送失败。

五、进阶技巧：如何提高消息的到达率？

消息发出去，用户收不到，这是最让人头疼的。我总结过几个常见原因：

原因一：用户关闭了通知权限。这个你控制不了，但可以在用户第一次拒绝后，通过小程序内的“引导页”提醒他去设置里打开。比如弹出一个提示：“您已关闭消息通知，请前往微信设置-通知-小程序通知中开启”。

原因二：发送频率过高。微信对每个用户每天能收到的订阅消息数量有限制（具体数值会动态调整，但通常不超过几条）。如果你一天内给同一个用户发了太多消息，后面的消息会被微信拦截。解决办法是：只在关键节点发送，比如发货、退款、上课提醒，而不是每个操作都发。

原因三：用户取消了订阅。用户可以在小程序详情页里手动取消订阅。这种情况你无法通过代码恢复，只能重新引导用户再次授权。

六、一个容易被忽略的细节：消息的“跳转页面”该怎么填？

在发送消息时，有一个page参数，它决定了用户点击消息后跳转到小程序的哪个页面。直接填一个固定的首页，这其实浪费了消息的价值。正确的做法是：根据消息内容，跳转到最相关的页面。比如发货通知，应该跳转到该订单的详情页；上课提醒，应该跳转到课程直播间。这样用户点击后的转化率会高很多。

如果你跳转的页面需要参数（比如订单ID），记得在page参数里带上。例如："page": "pages/order/orderDetail?orderId=123"。注意，这个页面路径必须是你在小程序里已经注册过的，否则点击后会提示“页面不存在”。

七、如果消息发送失败，怎么排查？

微信的发送接口会返回一个错误码，我列几个常见的：

40037：模板ID不正确。检查一下你复制的模板ID是不是多了空格，或者模板已经被删除了。

43101：用户拒绝授权。说明用户没有订阅这个模板，或者订阅已经过期。你需要重新引导用户订阅。

47001：data格式错误。检查一下你传的data字段里的key和模板里的是否完全一致，以及value是否超过了20个字符。

建议你在后端代码里，把每次发送的请求和返回结果都记录下来，方便排查。我自己的做法是：把日志写到数据库里，包括发送时间、用户openid、模板ID、返回码和返回信息。这样一旦用户反馈收不到消息，我就能快速定位问题。

八、扩展话题：消息推送和用户运营的结合

消息推送不仅仅是技术活，更是运营策略的一部分。我见过一些做得好的小程序，会在用户订阅时，给用户一个“订阅福利”，比如优惠券或者积分。这样用户更愿意授权。另外，消息的文案也很重要。比如同样是发货通知，“您的商品已发货”和“您的运动鞋已飞驰在路上，预计后天到达”，后者的点击率明显更高。

还有一个技巧：结合小程序的服务通知。除了订阅消息，小程序还有“服务通知”这个入口（就是微信聊天列表里那个“服务通知”的对话框）。虽然服务通知的触达率不如订阅消息，但它不需要用户授权，你可以用它发送一些非关键性的提醒，比如“您的会员即将过期”。两种通知方式结合使用，效果会更好。

最后想说的是，不要为了推送而推送。用户之所以愿意订阅，是因为他觉得这条消息对他有价值。如果你频繁发送无关紧要的内容，用户很快就会在设置里关掉你的通知，甚至直接卸载小程序。把每一次推送都当成一次与用户沟通的机会，而不是一次打扰。