帮你快速理解、总结文档立即下载

微信小程序

最近更新时间:2026-11-19 10:31:03
我的收藏
用户退出小程序后,业务侧无法再主动触达。微信提供的订阅消息可解决这一问题:消息由微信的服务通知送达用户,用户点击后可直接跳回小程序指定页面。本文以使用 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:小程序端发起订阅

调用 wx.requestSubscribeMessage 拉起微信授权弹窗,由用户确认是否接收消息。
注意:
该接口必须在用户点击事件的同步调用栈中发起,调用前不得存在 await 或异步回调。
uniapp 微信小程序(vue3)
uniapp 微信小程序(vue2)
微信原生小程序
<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-WEIXIN
if (!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 不需要驱动视图,直接挂在实例上,不放进 data
this.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-WEIXIN
if (!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,此为正常成功。订阅状态由微信维护,结果无需上报服务端。
调用失败时 fail 回调返回 errCode,完整错误码见 wx.requestSubscribeMessage。

步骤3:服务端下发消息

服务端需实现两个接口:
GET /api/config:供小程序端获取模板 ID,对应步骤二中 onLoad 的请求。
POST /api/notify/send:接收业务下发请求,获取 access_token 后调用微信的 subscribeMessage.send 完成下发。
本文示例基于 Node.js + Express,接入到已有服务时只需移植 getAccessToken 与下发逻辑。完整示例代码见 服务端 Demo,可直接下载运行。
1. 初始化项目
mkdir subscribe-demo && cd subscribe-demo
npm init -y
npm i express axios dotenv
2. 创建 .env 文件
WX_APPID=wx0000000000000000
WX_SECRET=your_app_secret
WX_TEMPLATE_ID=your_template_id
# developer 仅开发版可接收,trial 体验版,formal 正式版
WX_MINIPROGRAM_STATE=developer
# 仅用于本文示例先跑通流程,填入一个已订阅用户的 openid
DEMO_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 错误页而非 JSON
function 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。
端上发起订阅、返回值与错误码。
获取服务端调用凭证。
下发订阅消息、错误码。
服务器域名配置规则。