用户退出小程序后,业务侧无法再主动触达。微信提供的订阅消息可解决这一问题:消息由微信的服务通知送达用户,用户点击后可直接跳回小程序指定页面。本文以使用 Node.js 开发一个简单的小程序消息通知 Demo 为例,为您介绍使用微信小程序消息通知的基本流程。
说明:
示例仅供参考,正式上线前需要进一步完善,例如服务器负载均衡、接口并发控制、信息持久化存储等。此类优化操作不在本文介绍范围内,请开发者根据实际情况自行实现。
场景效果图
用户在小程序内点击按钮,微信拉起订阅授权弹窗,服务端通过服务通知推送消息:




前提条件
准备一台可以运行 Node.js 的公网开发服务器或云服务器。
业务服务器和微信服务器打通,指引文档。
记录以下两项信息,服务端需使用:
信息 | 获取位置 |
微信小程序的 AppID | 开发 > 开发管理 > 开发设置 |
微信小程序的 AppSecret | 同上(仅生成时可见,需自行保存) |
已具备获取用户
openid 的能力。下发消息须指定接收用户的 openid,由小程序登录流程获得:端上调用 wx.login 取得 code,服务端用 code 调用 auth.code2Session 换取 openid,并与业务用户关联存储。完整流程见 小程序登录。业务后台域名已加入小程序的 request 合法域名(开发 > 开发管理 > 开发设 > 服务器域名)。开发阶段可在微信开发者工具勾选:详情 > 本地设置 > 不校验合法域名跳过,该选项对正式版不生效。配置规则见 网络 > 使用说明。
运行环境:
项目 | 版本 |
微信客户端 | ≥ 8.0.40 |
小程序基础库 | ≥ 2.10.0 |
Node.js | ≥ 22,仅本文服务端示例需要 |
npm | ≥ 6.0 |
操作步骤
步骤1:申请消息模板
1. 进入功能 > 订阅消息。
2. 选择模板类型:一次性订阅 或 长期订阅。
3. 在公共模板库中按业务场景搜索模板,例如:订单、预约、咨询。
4. 选择模板,勾选需要的字段后提交(字段数量通常限制为 2~5 个)。
5. 在我的模板中获得模板 ID,后续步骤需使用。
一次性订阅和长期订阅两类模板差异如下:
对比项 | 一次性订阅 | 长期订阅 |
用户授权 1 次后 | 可下发 1 条消息 | 可持续下发,不限条数 |
需重复授权 | 是,每条消息对应一次授权 | 否,一次授权长期有效 |
类目要求 | 无,任意小程序可用 | 仅政务民生、医疗、交通、金融、教育等特定类目 |
模板来源 | 公共模板库,或自行申请 | 仅公共模板库按类目开放,不可自行申请 |
适用场景 | 多数业务 | 需持续推送且用户不便重复授权 |
步骤2:小程序端发起订阅
注意:
该接口必须在用户点击事件的同步调用栈中发起,调用前不得存在
await 或异步回调。<template><view><button @tap="onTapSubscribe">开启消息提醒</button></view></template><script setup>import { onLoad } from '@dcloudio/uni-app';// 模板 ID 不需要驱动视图,用普通变量保存即可let templateId = '';onLoad(() => {// 从业务接口取模板 ID 并提前存好,点击订阅时不能再等异步uni.request({url: 'https://your-domain.com/api/config',success: ({ data }) => {// 服务端返回 { code: 0, data: { templateId } }if (data && data.code === 0) {templateId = data.data.templateId;}},});});function onTapSubscribe() {// #ifdef MP-WEIXINif (!templateId) {uni.showToast({ title: '配置加载中,请稍后重试', icon: 'none' });return;}uni.requestSubscribeMessage({tmplIds: [templateId],success: (res) => {const result = res[templateId];// acceptWithAudio 同样表示同意const accepted = result === 'accept' || result === 'acceptWithAudio';if (accepted) {uni.showToast({ title: '已开启提醒', icon: 'none' });} else if (result === 'reject') {uni.showModal({title: '提醒未开启',content: '需允许接收消息,才能在离开小程序时收到提醒。',confirmText: '前往设置',success: (m) => { if (m.confirm) uni.openSetting(); },});}},fail: (err) => {console.error('[subscribe] fail', err.errCode, err.errMsg);},});// #endif}</script>
<template><view><button @tap="onTapSubscribe">开启消息提醒</button></view></template><script>export default {onLoad() {// 模板 ID 不需要驱动视图,直接挂在实例上,不放进 datathis.templateId = '';// 从业务接口取模板 ID 并提前存好,点击订阅时不能再等异步uni.request({url: 'https://your-domain.com/api/config',success: ({ data }) => {// 服务端返回 { code: 0, data: { templateId } }if (data && data.code === 0) {this.templateId = data.data.templateId;}},});},methods: {onTapSubscribe() {// #ifdef MP-WEIXINif (!this.templateId) {uni.showToast({ title: '配置加载中,请稍后重试', icon: 'none' });return;}uni.requestSubscribeMessage({tmplIds: [this.templateId],success: (res) => {const result = res[this.templateId];// acceptWithAudio 同样表示同意const accepted = result === 'accept' || result === 'acceptWithAudio';if (accepted) {uni.showToast({ title: '已开启提醒', icon: 'none' });} else if (result === 'reject') {uni.showModal({title: '提醒未开启',content: '需允许接收消息,才能在离开小程序时收到提醒。',confirmText: '前往设置',success: (m) => { if (m.confirm) uni.openSetting(); },});}},fail: (err) => {console.error('[subscribe] fail', err.errCode, err.errMsg);},});// #endif},},};</script>
Page({onLoad() {// 从业务接口取模板 ID 并提前存好,点击订阅时不能再等异步wx.request({url: 'https://your-domain.com/api/config',success: ({ data }) => {this.templateId = data.data.templateId;},});},onTapSubscribe() {wx.requestSubscribeMessage({tmplIds: [this.templateId],success: (res) => {const result = res[this.templateId];// acceptWithAudio 同样表示同意const accepted = result === 'accept' || result === 'acceptWithAudio';if (accepted) {wx.showToast({ title: '已开启提醒', icon: 'none' });} else if (result === 'reject') {wx.showModal({title: '提醒未开启',content: '需允许接收消息,才能在离开小程序时收到提醒。',confirmText: '前往设置',success: (m) => { if (m.confirm) wx.openSetting(); },});}},fail: (err) => {console.error('[subscribe] fail', err.errCode, err.errMsg);},});},});
wx.requestSubscribeMessage 接口
success 回调中 res[this.templateId] 的五种取值:返回值 | 含义 | 处理方式 |
accept | 同意 | 可下发消息 |
acceptWithAudio | 同意(含语音提醒) | 同 accept |
reject | 拒绝 | 引导至设置页 |
ban | 模板被封禁 | 停止下发 |
filter | 模板被过滤 | 暂不可下发 |
用户在授权弹窗中勾选总是保持以上选择后,后续调用将不再弹窗并直接返回
accept,此为正常成功。订阅状态由微信维护,结果无需上报服务端。步骤3:服务端下发消息
服务端需实现两个接口:
GET /api/config:供小程序端获取模板 ID,对应步骤二中 onLoad 的请求。
POST /api/notify/send:接收业务下发请求,获取 access_token 后调用微信的 subscribeMessage.send 完成下发。
1. 初始化项目
mkdir subscribe-demo && cd subscribe-demonpm init -ynpm i express axios dotenv
2. 创建 .env 文件
WX_APPID=wx0000000000000000WX_SECRET=your_app_secretWX_TEMPLATE_ID=your_template_id# developer 仅开发版可接收,trial 体验版,formal 正式版WX_MINIPROGRAM_STATE=developer# 仅用于本文示例先跑通流程,填入一个已订阅用户的 openidDEMO_OPENID=
3. 创建入口文件 server.js
require('dotenv').config();const express = require('express');const axios = require('axios');const app = express();app.use(express.json());/* ---------------- access_token ---------------- */// access_token 按 AppID 全局唯一,有效期 7200 秒。// 多实例部署须改为 Redis 等集中缓存,各实例独立刷新会相互失效,// 导致随机出现 40001。let tokenCache = { value: '', expireAt: 0 };async function getAccessToken() {if (tokenCache.value && Date.now() < tokenCache.expireAt) {return tokenCache.value;}const { data } = await axios.get('https://api.weixin.qq.com/cgi-bin/token', {params: {grant_type: 'client_credential',appid: process.env.WX_APPID,secret: process.env.WX_SECRET,},});if (data.errcode) {throw new Error(`获取 access_token 失败:${data.errcode} ${data.errmsg}`);}// 提前 5 分钟过期,避免边界失效tokenCache = {value: data.access_token,expireAt: Date.now() + (data.expires_in - 300) * 1000,};return tokenCache.value;}/* ---------------- 业务数据 ---------------- *//*** 取接收方 openid* 替换为查询自己的用户表(openid 的获取见「前提条件」)*/async function getOpenidByUserId(userId) {// return await db.user.findOpenid(userId);return process.env.DEMO_OPENID || null; // 演示用,便于先跑通流程}/*** 模板字段* 键名须与自己申请的模板完全一致,值需符合上表的格式限制*/function buildTemplateData(content) {return {thing1: { value: sanitize(content, 20) }, // thing:20 个字符以内time2: { value: formatTime(new Date()) }, // time:2026年11月5日 14:30};}/* ---------------- 接口 ---------------- */// 供端上在 onLoad 阶段提前取得模板 ID(见步骤二)app.get('/api/config', (req, res) => {res.json({ code: 0, data: { templateId: process.env.WX_TEMPLATE_ID } });});// 下发订阅消息app.post('/api/notify/send', asyncHandler(async (req, res) => {const { receiverId, content } = req.body;const openid = await getOpenidByUserId(receiverId);if (!openid) return res.json({ code: 404, message: 'openid not found' });const token = await getAccessToken();const { data: result } = await axios.post(`https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=${token}`,{touser: openid,template_id: process.env.WX_TEMPLATE_ID,page: 'pages/index/index', // 点击消息后打开的小程序路径miniprogram_state: process.env.WX_MINIPROGRAM_STATE,lang: 'zh_CN',data: buildTemplateData(content || '您有一条新消息'),});// errcode 为 0 表示已下发,其余为失败if (result.errcode !== 0) {console.error('[send] failed', result.errcode, result.errmsg);}res.json({code: 0,data: { sent: result.errcode === 0, errcode: result.errcode, errmsg: result.errmsg },});}));/* ---------------- 工具 ---------------- */// 过滤 emoji 与换行,并截断至模板长度上限function sanitize(text, max) {const clean = String(text)// emoji 主区、符号区,以及变体选择符 FE0F(如 ❤️ 的隐藏字符).replace(/[\\u{1F000}-\\u{1FAFF}\\u{2600}-\\u{27BF}\\u{FE0F}\\u{20E3}]/gu, '').replace(/\\s+/g, ' ') // 换行与连续空格归一.trim();return clean.slice(0, max) || '新消息';}function formatTime(d) {return `${d.getFullYear()}年${d.getMonth() + 1}月${d.getDate()}日 ` +`${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;}// Express 4 不会自动捕获 async 路由抛出的异常,需包一层,// 否则失败时返回的是含堆栈的 HTML 错误页而非 JSONfunction asyncHandler(fn) {return (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);}app.use((err, req, res, next) => {console.error('[error]', err.message);res.status(500).json({ code: 500, message: err.message });});app.listen(3000, () => console.log('server on http://localhost:3000'));
4. 启动服务
node server.js
步骤4:验证
订阅可直接在微信开发者工具中完成,无需真机。工具需登录开发者本人的微信账号,授权记录会绑定到该账号的
openid。1. 在开发者工具中打开小程序,点击订阅入口,在弹窗中选择允许。
2. 调用服务端的下发接口,确认返回
errcode: 0。curl -X POST http://localhost:3000/api/notify/send \\-H "Content-Type: application/json" \\-d '{"receiverId":"业务用户ID","content":"测试消息"}'
3. 在手机微信的服务通知中查看消息。
4. 点击消息,小程序将跳转至
page 参数配置的路径。说明:
消息由微信服务通知送达,需在手机微信中查看,开发者工具不接收消息。
miniprogram_state 为 developer 时仅开发版可接收消息。使用体验版或正式版测试时需同步改为 trial 或 formal,否则消息不会送达,但下发接口仍返回成功。避免用户在前台时收到重复通知
问题说明
服务端调用 subscribeMessage.send 下发订阅消息时,微信不会判断用户当前是否正在使用小程序,只要用户已授权,消息都会送达「服务通知」。服务端无法自行得知用户是否在小程序前台。因此,如果业务在每次有新呼叫时都直接下发订阅消息,就会出现以下情况:用户正停留在小程序内,通话页面已经正常拉起,手机却同时弹出一条服务通知。这条通知和页面内的呼叫重复,会干扰用户。
推荐方案:业务侧心跳上报
由业务侧自行实现心跳上报,服务端根据心跳判断用户是否在前台,仅在用户不在前台时下发订阅消息:
1. 端上上报心跳:小程序在前台时每 3 秒向业务服务端上报一次心跳,切到后台时立即停止上报。关闭微信后小程序无法再发出请求,心跳也会随之中断。
2. 服务端判断后下发:服务端记录每个用户最近一次心跳时间,超时时间设为 6 秒(即连续 2 次未收到心跳)。有新呼叫时:
心跳未超时:用户在前台,不下发订阅消息,由页面内展示呼叫。
心跳已超时:用户已切后台、锁屏或关闭微信,下发订阅消息。
参考文档
文档 | 内容 |
能力说明、下发规则、模板字段限制。 | |
获取用户 openid 的完整流程。 | |
服务端用 code 换取 openid。 | |
端上发起订阅、返回值与错误码。 | |
获取服务端调用凭证。 | |
下发订阅消息、错误码。 | |
服务器域名配置规则。 |