uni.requestSubscribeMessage 必须在用户点击事件第一行立即同步调用，任何异步操作（如 await、setTimeout）或非直接点击上下文（如 login 回调）均会触发“fail can only be invoked by user TAP gesture”错误；检查订阅状态需 uni.getSetting({withSubscriptions: true})，否则无 subscriptionsSetting 字段；后端发送时 data 每个字段必须为 {value: "..."} 结构，且 template_id、touser、access_token 须严格准确。
uni.requestSubscribeMessage 必须在用户点击中立即同步调用
微信强制拦截所有非用户主动触发的调用，哪怕只加一个 await 或 setTimeout 就会报 fail can only be invoked by user TAP gesture。这不是兼容性问题，是平台硬性限制。
常见错误包括：
- 把
uni.requestSubscribeMessage放在uni.login成功回调里 —— 此时已脱离点击上下文 - 按钮绑了
@click="handleClick"，但handleClick里先查登录态、再 await 接口，最后才调用 —— 中间任何异步操作都会导致失败 - 没给
<button>设置open-type="subscribeMessage"（uni-app 3.0+ 推荐）—— 部分基础库版本下静默失效
正确做法：点击事件函数体内第一行就调用，不包裹、不延迟、不判断。授权弹窗是否出现，只取决于这个调用是否发生在真实点击链路中。
uni.getSetting 检查订阅状态必须传 withSubscriptions: true
不加这个参数，res 里压根没有 subscriptionsSetting 字段，等于白查。很多开发者以为“查了权限”，其实连开关都没摸到。
返回结果关键字段：
-
mainSwitch为false：系统级通知总开关关闭，需引导用户去系统设置开启，调用uni.openSetting({ withSubscriptions: true })才有效 -
itemSettings['YOUR_TEMPLATE_ID']为undefined：不是拒绝，是用户从未见过该模板，此时才是调用uni.requestSubscribeMessage的合理时机 -
itemSettings['YOUR_TEMPLATE_ID']为'reject'：用户点过“拒绝”，再次调用不会弹窗，必须走uni.openSetting引导手动开启
注意：itemSettings 只在 withSubscriptions: true 下存在，且字段名大小写、拼写必须和微信后台模板详情页里的 name 完全一致（如 thing1，不能写成 THING1 或 keyword1）。
.NET 后端发消息时 data 字段结构必须严格匹配模板定义
后端调用 https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=xxx 时，data 里每个字段都必须是对象，且含 value 键。直接写字符串会报 {"errcode":47001,"errmsg":"data format error hint"}。
典型错误写法：
{ "thing1": "订单已发货" }
正确写法：
{ "thing1": { "value": "订单已发货" } }
其他要点：
-
touser必须是用户真实openid，不是unionid -
template_id必须是微信公众平台审核通过的完整字符串，不能截断或漏字符 -
access_token必须缓存并自动刷新（2 小时有效期），不能每次请求都重新拉取，否则极易触发频率限制
个性化字段如何动态填入 template data
模板字段名（如 thing1、time2）是固定的，但 value 内容可以完全由前端传参决定。比如物流通知模板里 thing1 对应商品名，time2 对应预计送达时间，这些值在调用后端接口时一并传过去即可。
实操建议：
- 前端在用户点击授权成功后，立刻把当前业务上下文数据（如订单号、商品名、时间）和
openid一起 POST 给后端 - 后端组装
data时，字段名严格对照模板详情页，value填入前端传来的实际值 - 如果字段类型有要求（如
time2要求"2026-06-17 15:30"格式），前端应在传参前格式化好，避免后端做类型转换引发异常
真机测试前务必确认：模板 ID 已审核通过、基础库 ≥ 2.10.0、manifest.json 中 AppID 正确、后端 access_token 缓存机制已上线 —— 少一个环节，消息就发不出去。
