小程序开发

南京小程序订阅消息怎么配置?2026 一次性与长期订阅、授权次数及下发失败排查清单

2026年11月14日

专业技术文章

南京小程序订阅消息怎么配置?2026 一次性与长期订阅、授权次数及下发失败排查清单

发布时间:2026年11月14日
|作者:易企达网络|来源:南京易企达网络科技有限公司||
浏览:1,938
南京小程序订阅消息怎么配置:模板、授权次数、下发与错误码核对清单
封面:订阅消息的问题多数不在代码,而在模板、授权次数与下发参数这三处。

「南京小程序订阅消息怎么配置」可以按四段收敛:先在后台选好模板并记下字段与模板 ID,再由用户点击触发前端授权,服务端记录可下发次数并缓存调用凭证,最后调用下发接口并按错误码回收结果。订阅消息不是「后台配好就能随时推」,它把下发权限交给了用户的一次次授权,业务侧必须自己维护次数台账。下面按能力选型、配置顺序、次数记法、模板字段、错误码反查、调用节奏、真机验证逐段展开,全部给出可套用的核对表;接口规则、模板类目与额度口径会调整,实现时以微信开放文档和微信公众平台当期公示为准。

把判断放在前面:「用户收不到消息」绝大多数不是下发接口写错,而是三件事之一——用户没有真正订阅成功、一次性订阅的次数已经发完、模板 data 的字段名或格式与后台模板对不上。这三类分别对应前端授权回调、服务端次数台账、请求体结构,按这个顺序取证通常能直接定位,不需要反复改代码或重发消息。

一、先分清三类消息

模板消息已不再作为新增申请入口,现行方案是订阅消息;客服消息则依附于用户发起的会话。三者触发方式、额度规则、适用场景完全不同,混用会直接导致功能设计从起点就走偏。

小程序三类消息对照:一次性订阅授权一次发一条、长期订阅限特定类目、客服消息会话内回复
图 1:三类消息的触发条件不同,先选型再决定埋点位置。
类型 触发方式 额度规则 适用范围 常见误用
一次性订阅消息 用户点击按钮后由 wx.requestSubscribeMessage 拉起授权 用户每授权一次,服务端可下发一条;同一模板多次授权可累加 面向绝大多数类目,订单状态、预约提醒、审核结果等场景 把一次授权当成永久可发,不做次数台账
长期订阅消息 同样需要用户授权,但模板需先申请 额度与有效期按平台对该类模板的规则执行 仅部分公共服务类目开放,如政务民生、医疗、交通、金融、教育等方向 普通商业类目按长期订阅设计,上线时才发现没有对应模板
客服消息 用户在小程序内发起会话后,在平台规定的会话窗口内回复 由会话窗口与消息条数限制约束 咨询答复、售后沟通等即时交互 拿它替代业务通知,用户未发起会话时无法下发

选型结论通常很直接:商业类小程序基本走一次性订阅,因此业务设计的重点不是「找一条能一直发的模板」,而是「在合适的节点多给用户几个授权入口,并把次数记准」。长期订阅能不能用,取决于后台模板库里是否真的存在对应类目的模板,这一点要在设计阶段先查,不要等到联调。

二、从配置到下发的六步

下面六步把前台与后台的动作排成一条线,每一步都列出输出物与常见断点,可以直接当作联调检查表使用。

小程序订阅消息配置下发六步:后台选模板、记字段与模板 ID、点击触发授权、服务端存次数、缓存调用凭证、回收错误码
图 2:六步里前后两段在后台与前端,中间三段都在服务端。
顺序 位置 操作 输出物 常见断点
1 选模板 微信公众平台「订阅消息」 从公共模板库选用或申请模板,确认类目与场景匹配 模板 ID 与字段清单 选了本主体无权限的模板
2 记字段 接口文档或配置表 把模板里的字段名、类型、顺序逐项抄进服务端配置 字段映射表 字段名带序号,凭印象写成 thing1、time2 之外的名字
3 触发授权 小程序前端 在用户点击事件的回调里调用 wx.requestSubscribeMessage,逐个模板 ID 处理返回值 授权结果记录 放在页面 onLoad 里自动调用,弹窗不出现
4 存次数 开发者服务器 按用户与模板维度记录可下发次数,下发后按结果回写 次数台账 只记授权成功,不回写下发结果
5 缓存凭证 开发者服务器 集中获取并缓存 access_token,临近过期再刷新 可用的调用凭证 每次下发临时换取,多实例互相顶掉
6 回收结果 开发者服务器 调用下发接口,记录请求体与返回码,失败按错误码归类 下发日志 只记成功失败,不留返回码原文

第 3 步有一个稳定的约束:订阅授权必须由用户点击触发。把 requestSubscribeMessage 写进页面加载或定时器里,通常拿不到弹窗,也就拿不到任何可下发次数。第 6 步的日志则是后面所有排查的地基,请求体里模板 ID、touser、data、page 与返回码都建议原样留档,遇到 43101 时才能反查次数到底在哪一步被消耗。

三、授权次数怎么记

一次性订阅的额度是「按用户、按模板」累加的,不是按小程序全局计一个数。下表把常见情形与服务端应做的动作列全,可以直接映射成一张订阅记录表。

情形 次数变化 服务端动作 留档内容
用户点击并同意某个模板 该用户该模板可下发次数增加 按 openid 加 template_id 记一条增量 授权时间、模板 ID、前端返回的 accept 状态
用户拒绝或取消某个模板 不增加 不写次数,记录拒绝状态供前端提示 reject 状态与触发页面
同一模板多次授权 次数累加 在原有记录上累加,不去重 每次授权的增量与时间
用户勾选「总是保持以上选择」 后续不再弹窗,按平台规则继续累加 前端不再依赖弹窗回调,改由服务端台账判断 设置状态变更时间
用户在设置页或微信服务通知里关闭 后续下发会被拒绝 收到 43101 时把台账标记为不可用 错误码与发生时间
下发成功 按平台规则扣减 回写台账与下发日志 请求体、返回码、消息内容摘要

把次数台账放在服务端是必要的:前端回调只在授权当下存在,用户卸载重装、换设备、清理缓存之后都不会补发。另外一个常见误区是把「授权成功」等同于「一定能发出去」——用户后续在设置页关闭订阅,服务端仍会收到 43101,因此台账需要能被失败结果反向修正。

四、模板字段与 data 结构

模板里的字段名与类型由后台模板固定,开发者只能往这些字段里填值,不能自行新增或改名。47003 之所以高频,几乎都出在这一层的细微偏差上。

检查项 规则 常见偏差 取证方式
字段名 与后台模板展示的键完全一致,通常带序号,例如 thing1、time2、amount3 自造字段名、漏抄序号、大小写不一致 后台模板截图与请求体逐字比对
值结构 每个字段按 {value: 具体内容} 的形式传入 直接传字符串、缺少 value 层、多套一层数组 打印完整请求体
类型与长度 thing、time、number、amount、phrase 等类型各有取值格式与长度规则 超长文本、日期格式不符、数字传成字符串 对照模板字段类型逐项校验
空值 模板列出的字段需要按规则填写 可选字段直接省略或传空字符串 请求体完整性检查
page 路径 需为已发布版本中真实存在的页面路径 填了体验版路径、路径带参数或拼写错误 与线上包 app.json 比对
版本环境 联调时通过 miniprogram_state 指定开发版、体验版或正式版 联调用了正式版环境却指向尚未发布的页面 下发日志里的环境参数

建议在服务端加一层模板配置的集中校验:把每个模板 ID 对应的字段清单写成配置,下发前先按类型和长度检查一遍再发请求。这样 47003 会在本地暴露,而不是等到线上消息发不出去才发现。

五、下发失败按错误码反查

微信开放文档「发送订阅消息」页面公开了主要错误码与处理建议,可以直接拿来当排查表。下表按官方描述整理,并补上每项优先检查的位置。

订阅消息下发失败六个错误码:43101 用户未订阅、47003 模板参数错误、40037 模板 ID 无效、40003 openid 无效、41030 页面路径不存在、45168 命中敏感词
图 3:错误码把失败原因分成订阅、参数、凭证、文案四类。
错误码 官方描述 优先检查
40001 invalid credential,access_token 无效或不是最新 核对 AppSecret,确认没有多个服务各自刷新 token
40003 invalid openid,不合法的 OpenID 核对 touser 是否为本小程序的 openid,而非公众号或别的小程序
40014 invalid access_token,不合法的调用凭证 核对 token 有效期与缓存刷新逻辑
40037 invalid template_id,不合法的模板 ID 重新从公众平台取一次,确认模板未被删除
43101 用户未订阅消息 检查授权回调结果,以及一次性订阅的次数之前是否已下发完
43107 订阅消息能力封禁 检查账号是否被限制,以及该模板 ID 是否被封禁
43108 并发下发消息给同一个用户 检查是否在同一时间向同一用户下发了多条
45168 命中敏感词 检查下发文案里是否带有敏感词
47003 参数错误 按模板检查 data 结构、字段名与各关键词是否满足对应规则
41030 页面路径不正确 确认 page 指向线上已发布版本中存在的页面

反查时建议固定一个顺序,避免多项同时排查时互相干扰:先看授权回调与次数台账(对应 43101),再看请求体字段(对应 47003、41030),然后看模板 ID 与 openid(对应 40037、40003),最后看调用凭证、文案与并发(对应 40001、40014、45168、43108)。

顺序 检查对象 取证方式
1 前端授权回调里每个模板 ID 的返回值 真机日志,确认是 accept 还是 reject
2 服务端次数台账的剩余可下发数 订阅记录表按 openid 与 template_id 查询
3 模板字段与请求体 data 后台模板截图加完整请求体原文
4 access_token 的获取时间与缓存 服务端凭证刷新日志
5 touser 是否为当前小程序 openid 与登录链路里的用户表比对
6 page 是否在线上版本存在 与已发布包的 app.json 比对
7 下发文案与并发节奏 消息内容留档与下发队列日志

六、调用凭证与下发节奏

把 access_token 和并发当成独立一层来设计,能消掉一批看起来像「消息丢了」的问题。下表列出常见的落地口径。

项目 规则 落地做法
调用凭证有效期 access_token 有效期通常为 7200 秒 服务端集中缓存,临近过期再刷新,不在每次下发时临时换取
多实例部署 各实例各自刷新会互相顶掉刚取到的凭证 共享缓存或由单点服务统一负责刷新与分发
同一用户并发 短时间向同一用户下发多条会触发 43108 合并可合并的消息,或走串行队列并留出间隔
请求留痕 每次下发的模板 ID、touser、请求体与返回码都需要可回溯 写结构化下发日志,按错误码建索引
失败重试 参数类与订阅类错误重试不会变成功 仅对凭证类错误做有限重试,其余归入人工排查队列

七、真机验证与上线前自检

订阅授权弹窗在开发者工具里不稳定,验证环节必须放到真机。下面这份清单覆盖从模板到下发记录的全链路,每一项都能对应一次操作或一条日志。

  1. 在公众平台确认所用模板确实存在于当前主体的模板库,记录模板 ID、字段清单与类目。
  2. 核对模板字段与服务端配置表逐字一致,包含带序号的键名与字段类型。
  3. 确认 requestSubscribeMessage 写在用户点击事件的回调里,而不是页面加载或定时器中。
  4. 真机上逐一点选多个模板,记录每个模板 ID 返回的 accept、reject 或 ban 状态。
  5. 核对服务端次数台账在授权后增加、在下发后按结果回写,并模拟用户关闭订阅后的 43101。
  6. 构造一次字段超长、一次字段名写错、一次 page 不存在的请求,确认返回码与日志可区分。
  7. 确认 access_token 由单点缓存刷新,多实例部署下不会互相顶掉。
  8. 确认下发日志保留了模板 ID、touser、完整请求体与返回码原文,能按错误码检索。

勾选过「总是保持以上选择」之后,同一个模板不会再弹窗,联调时容易误判成授权代码失效。开发阶段可以在小程序时间胶囊的「设置 → 订阅消息」里把对应模板关闭后重新打开,或换测试账号验证;这类操作属于调试手段,不应写进线上业务逻辑。

八、常见问题

问:小程序订阅消息怎么配置

答:在公众平台「订阅消息」里选模板并记下模板 ID 与字段清单,前端在用户点击事件里调用 wx.requestSubscribeMessage 拉起授权,服务端按 openid 与模板维度记录可下发次数并缓存 access_token,最后调用下发接口并记录返回码。四个环节缺一个,消息就发不出去。

问:小程序订阅消息收不到

答:按三段查:先看前端授权回调里该模板是否返回 accept;再看服务端次数台账是否还有可下发数,用户可能在设置页关闭过订阅;最后看下发返回的 47003 或 41030,确认字段与 page 路径无误。真机验证,开发者工具里的授权弹窗不稳定。

问:小程序一次性订阅消息可以发多次消息吗

答:一次授权对应一条可下发额度,同一模板多次授权可以累加,所以能在业务里多设几个授权入口。用户勾选「总是保持以上选择」后不再弹窗,额度按平台规则继续累加,服务端仍要自己记台账,不能假定可以无限下发。

问:小程序长期订阅消息如何开通

答:长期订阅只对部分公共服务类目的模板开放,例如政务民生、医疗、交通、金融、教育等方向,需要主体与服务类目符合要求并申请到对应模板。商业类小程序通常没有对应入口,应先在公众平台模板库确认可用模板,再决定业务方案,不宜按长期订阅设计。

问:小程序订阅消息发送次数

答:一次性订阅按用户、按模板累计,用户每授权一次增加相应额度,下发后按平台规则扣减;同一用户短时间内并发下发会触发 43108。额度口径与累加规则以平台当期公示为准,服务端建议按 openid 加 template_id 建台账并保留每次增量与扣减记录。

问:小程序模板消息怎么申请

答:模板消息已不再作为新增申请入口,现行方案是订阅消息。做法改为在公众平台「订阅消息」的公共模板库里选用模板,或按类目申请模板;拿到模板 ID 后再走前端授权与服务端下发流程。历史项目里基于模板消息的代码需要按订阅消息改造。

问:小程序消息推送授权怎么设置

答:授权入口在小程序端,由用户点击按钮触发 wx.requestSubscribeMessage,回调里按模板 ID 逐项读取结果。用户后续可在小程序设置页或微信服务通知里调整接收状态;勾选「总是保持以上选择」后不再弹窗,需要在设置里关闭再打开才能重新验证。

问:小程序一次性订阅消息怎么取消

答:用户侧可在小程序设置页的订阅消息列表里关闭对应模板,也可在微信服务通知里取消接收。业务侧不能替用户取消,但会在下发时收到 43101;收到后宜把次数台账标记为不可用,并停止对该用户该模板的继续下发。

九、可复用的核验路径

把上面的判断落到三条可自行复现的路径。其一,打开微信开放文档的「发送订阅消息」与 wx.requestSubscribeMessage 页面,逐项比对请求参数、返回状态与错误码说明,尤其核对 43101、47003、40037 的官方描述。其二,在公众平台后台核对模板库里实际存在的模板 ID、字段清单与主体类目,这决定了长期订阅是否可用。其三,用真机走一次完整链路,把授权回调、次数台账、下发请求体与返回码按顺序记进同一条日志,之后任何「收不到」都能沿这条日志反查到具体环节。模板类目、额度规则与接口参数会调整,任何实现以平台当期公示与后台实际显示为准。

配图说明:本文部分配图使用人工智能生成合成技术制作。

《南京小程序订阅消息怎么配置?2026…》是我们在南京做小程序开发时的实际实施记录。费用与交付范围以双方合同及平台当期规则为准。需要评估自己的项目,可以到联系页留下需求与预算范围。

相关文章

南京小程序图片上传与压缩怎么配置?2026 选图、压缩、上传链路与失败排查清单

南京小程序图片上传与压缩怎么配置?2026 选图、压缩、上传链路与失败排查清单

小程序图片上传是否稳定,取决于四段链路:选图参数是否用对、压缩是否在正确时机执行、上传地址是否在合法域名内、返回地址是否...

2026年11月21日

南京小程序 web-view 怎么配置?2026 业务域名、双向通信、跳转限制与白屏排查清单

南京小程序 web-view 怎么配置?2026 业务域名、双向通信、跳转限制与白屏排查清单

小程序 web-view 能否按预期工作,取决于四个前置条件:主体类型、业务域名与校验、通信是否遵守 postMessa...

2026年11月21日

南京小程序分享转发怎么配置?2026 转发灰色排查、带参归因与朋友圈限制清单

南京小程序分享转发怎么配置?2026 转发灰色排查、带参归因与朋友圈限制清单

小程序分享转发的可用前置条件是页面级回调、未隐藏菜单、认证备案与版本兼容。转发给朋友与分享到朋友圈是两套独立能力,字段、...

2026年11月20日

南京小程序数据埋点怎么设置?2026 留存口径、事件模型与上报失败排查清单

南京小程序数据埋点怎么设置?2026 留存口径、事件模型与上报失败排查清单

小程序数据埋点能否支撑留存分析,结论取决于指标口径、事件模型与上报链路是否先定死。基础统计做大盘校准,自定义分析做单事件...

2026年11月20日

南京小程序本地存储怎么配置?2026 容量上限、隔离规则、同步异步与清理策略清单

南京小程序本地存储怎么配置?2026 容量上限、隔离规则、同步异步与清理策略清单

小程序本地存储的结论先行:storage 独立于代码包,按用户维度隔离,单 key 上限 1MB、同一用户同一小程序总量...

2026年11月19日

南京小程序版本灰度与回滚怎么操作?2026 全量与分阶段发布、版本回退与异常反查清单

南京小程序版本灰度与回滚怎么操作?2026 全量与分阶段发布、版本回退与异常反查清单

小程序版本发布与回退的结论先行:全量发布即时覆盖用户,分阶段发布在十五天内按自定义比例逐步覆盖并默认到期全量;撤销分阶段...

2026年11月19日