{errcode:40037,errmsg:invalid template_id}这个报错几乎是每个做微信小程序消息推送的人都会撞上的一次墙。它不像超时、网络抖动那样带点玄学色彩而是一个非常干脆的确定性错误你递上去的那串 template_id服务端不认。可偏偏这串 ID 肉眼看起来人畜无害几十位字母数字加连字符跟官方文档示例长得一模一样粘贴过去就是报错查半天也查不出所以然。我见过有人在这上面耗掉整整一个下午最后发现是复制的时候把换行符带进去了也见过整个环境从测试号切到正式号模板 ID 没跟着换上线第一天才炸。这篇东西就是把 40037 这个错误从报错文本拆到数据链路的完整过程记录包含成因分类、定位顺序、可复制的验证代码、周边错误码联动排查以及几条我认为最值钱的工程化建议。不管你是刚接消息推送的新手还是已经发过几万条通知、想把手上的链路做扎实的老手应该都能从里面捞到点东西。1. 先把 40037 说透它到底在报什么1.1 报错文本的三层信息量这行 JSON 短得可怜但它其实给了三层信息。第一层是errcode 40037这是微信服务端定义的业务错误码含义固定为模板 ID 无效属于参数校验类错误不是网络错误、不是权限错误、也不是频率错误。第二层是errmsg 里的 invalid template_id它进一步缩小了范围——问题出在 template_id 这个字段本身而不是 access_token 过期、不是 openid 不对、不是 data 里的字段类型不匹配。第三层是隐含信息这个错误在请求到达业务逻辑之前就被拦下来了也就是说你的网络是通的、access_token 大概率是有效的否则会先报 40001 或 42001服务端读到了你的 template_id然后在自己的模板库里查了一遍没查到直接打回。理解这三层非常重要因为它决定了你该往哪个方向找。很多人一看报错就去翻 access_token折腾半天换 token、刷新缓存毫无意义——40037 跟你 token 好不好没关系token 有问题会给你另外的错误码。同样也不用去查用户的 openid 对不对、订阅次数够不够那些是后面几个错误码才管的事。40037 是一个纯粹的标识符对不上号的问题排查方向只有一个你用的这串 ID跟服务端认为你应该用的那串不是同一个东西。我习惯把这类错误叫身份类错误跟权限类错误比如 40013 无效 appid、40165 无效的请求来源和业务类错误43101 用户拒绝接收、45009 接口调用超限区分开。身份类错误的排查成本通常很低但前提是你得知道去哪儿比对。1.2 为什么它偏偏爱在联调阶段冒头这个错误有个很讨厌的特点它特别偏爱在第一次跑通和环境切换这两个时刻出现。原因不复杂因为 template_id 是整个消息推送链路里唯一一个既需要人工复制、又会随环境变化、还长得极其相似的配置项。appid 和 secret 你通常会放在配置文件或者环境变量里改一次记一辈子openid 是从登录态里动态取出来的不会写错access_token 是程序自动换的也不经人手。唯独 template_id你得登录后台、进模板库、选中一个模板、点复制、粘贴到代码里。这个动作里塞满了人为失误的可能复制漏了几位、多了个空格、把公众号后台的 ID 粘到小程序代码里、测试环境配好了忘了同步到生产配置。更要命的是微信小程序的模板体系经历过一次大改版。早期的模板消息接口在若干年前就已经下线取而代之的是订阅消息。两套体系在概念上高度相似都叫模板、都有 template_id、都是往用户微信里推一条卡片但接口地址、模板库、ID 空间完全是两回事。于是一批照着我几年前的老教程敲代码的人拿着新模板库里的 ID去调一个已经不存在的接口或者在两种模板之间来回横跳报错自然就来了。这也是为什么我强调看到 40037第一反应不应该是ID 打错了而是我这条链路用的到底是哪一套模板体系。1.3 我的三问定位法真到了线上报警的时候没时间做学术研究。我一般按照下面这个顺序连问三个问题绝大多数情况在第一问或第二问就出结果了。第一问这串 ID 是从哪个后台复制的小程序订阅消息的模板库在小程序后台 - 功能 - 订阅消息里公众号模板消息的模板库在公众号后台 - 广告与服务 - 模板消息里。两个后台、两套 ID。如果代码调的是/cgi-bin/message/subscribe/sendID 就必须来自小程序后台调的是/cgi-bin/message/template/sendID 就必须来自公众号后台。串了必报 40037。第二问这串 ID 现在还在不在模板列表里模板会因为类目不符、内容违规、平台调整而下架下架之后历史 ID 就失效了。你以为配置没动过实际上服务端那边已经把你这条模板摘掉了。这种情况在昨天还好好的今天突然全挂的场景里占比相当高。第三问这串 ID 是不是当前环境该用的测试号有小程序的测试号正式号有正式号的模板库两者 ID 不通用。很多团队测试环境和生产环境共用一个配置仓库切分支的时候漏改了某个 key本地能跑、线上就炸。三个问题问完基本能锁定病灶。如果三问都过了还是报错那就得怀疑隐形字符、接口地址拼错、或者 ID 被截断了这些放到后面细讲。2. 模板 ID 的来源与生命周期管理2.1 订阅消息与公众号模板消息是两套独立系统这是 40037 最大的一个坑值得单独拎出来讲。很多人脑子里的模型是微信提供了模板消息能力小程序和公众号只是两个入口这个理解是错的而且错得很危险。小程序侧的叫订阅消息用户在小程序里主动点击授权你才能发发一次消耗一次授权次数。接口是POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_tokenxxx请求体里带template_id、touser、page、data、miniprogram_state、lang。公众号侧的叫模板消息走的是POST https://api.weixin.qq.com/cgi-bin/message/template/send?access_tokenxxx请求体里带touser、template_id、url、miniprogram、data。两套系统的 template_id 是完全独立的两套 ID 空间长得都一样一长串字母数字连字符但互不相认。你把小程序订阅消息的 ID 拿去调公众号接口服务端在公众号模板库里查不到返回 40037反过来也一样。我见过最典型的一幕是某团队做的是小程序但负责推送的同事之前做公众号出身顺手把公众号那套代码抄过来接口地址忘了改ID 也没换联调的时候一头雾水查了两天才发现问题出在抄错了作业本。所以看到 40037第一件事不是看 ID 长什么样而是看接口地址和 ID 来源是不是同一个体系。这个检查十秒钟就能做完但能省下十几个小时。2.2 模板 ID 的获取路径与模板选型正规获取路径大致是这样走的登录小程序管理后台左侧找到订阅消息入口进入公共模板库按你的业务类目和需求搜索关键词比如订单预约提醒审核结果选中模板后点击选用系统会要求你勾选需要使用的关键词字段确认之后一条属于你的模板就生成出来了列表里能看到模板标题、字段列表和一串模板 ID点复制即可。这里有个容易被忽略的细节同一个公共模板不同小程序选用后生成的模板 ID 是不一样的。它是公共模板 你的账号共同生成的实例 ID不是公共模板本身的编号。所以你不能从别人的代码里抄一个 ID 过来直接用哪怕你们用的是同一款订单支付成功通知模板你的 ID 也跟他不同。这一点让抄 GitHub 上的 Demo 直接跑这条路彻底走不通——Demo 里的 ID 是人家的你拿去必然 40037。选模板的时候还有两个实操层面的取舍。一是字段数量和类型选少了不够用选多了每条消息里必须填的 key 就多漏一个就报 47003参数不合法所以我通常只勾真正要展示的 3 到 5 个字段宁缺毋滥。二是一次性订阅还是长期订阅长期订阅只有特定行业类目才开放绝大多数小程序只能拿到一次性订阅用户点一次授权只能发一条这个限制会直接影响你的业务设计后面会细说。2.3 模板的下架、删除与版本漂移模板不是配一次就一劳永逸的。它有生命周期而且这个生命周期不完全由你控制。第一种情况是主动删除。有人在后台清理模板列表觉得某个模板不用了顺手删掉代码里的 ID 就变成了孤儿。这种还算好查因为变更记录是存在的。第二种情况是被动下架。平台会定期巡检模板内容如果模板被你改过、填了与实际类目不匹配的内容或者平台策略调整历史模板可能被回收。这时候你的代码一个字没动、配置一行没改报错却突然开始刷屏。这类故障最难查因为没人动过这四个字会把人带偏。第三种是版本漂移。你在公共模板库里选了一个模板后来这个公共模板被平台更新了字段名改了、字段顺序变了、甚至整体替换你手里的实例可能同步更新也可能保留旧版。如果你的代码里硬编码了thing1、time2这类字段 key模板一变虽然不至于立刻报 40037ID 还在但会报 47003。真正导致 40037 的是模板整体被回收的那种情况。应对办法很朴素把模板 ID 当成配置项而不是常量并且给它配一个健康检查。我通常会在系统里维护一张模板表记录模板 ID、用途、字段清单、最近一次人工核对时间。上线前跑一个校验脚本对每个 ID 发一条测试消息给内部账号失败了就卡住发布流程。这个脚本写起来不到五十行但能挡掉绝大部分上线才发现模板挂了的事故。3. 五个高频成因逐个击破3.1 环境串号测试号、体验版、正式版混用小程序开发过程中会同时存在多个环境本地开发用的测试号、体验版、正式版。每个环境对应不同的 appid也就对应不同的模板库、不同的模板 ID。串号的典型症状是本地跑得好好的发到体验版就报 40037。原因是你本地的配置文件里写的是测试号的模板 ID而体验版用的是正式 appid 换来的 access_token拿正式 token 去查测试号的模板当然查不到。这类问题的根子在于配置管理。我的做法是强制要求模板 ID 与 appid 绑定在同一个配置块里不要让它们分散在各自的配置文件里。比如用一份mp.config.js把appid、secret、templateIds三者放在一起按环境导出。这样切换环境的时候是整块切换不会出现appid 换了、模板 ID 忘了换的半吊子状态。代码长这样// mp.config.js const ENVS { dev: { appid: wx_test_appid_placeholder, secret: process.env.MP_SECRET_DEV, templateIds: { orderPaid: DEV_TEMPLATE_ID_PLACEHOLDER, auditResult: DEV_AUDIT_TEMPLATE_ID_PLACEHOLDER } }, prod: { appid: wx_prod_appid_placeholder, secret: process.env.MP_SECRET_PROD, templateIds: { orderPaid: PROD_TEMPLATE_ID_PLACEHOLDER, auditResult: PROD_AUDIT_TEMPLATE_ID_PLACEHOLDER } } }; export default function getMpConfig() { const env process.env.MP_ENV || dev; const cfg ENVS[env]; if (!cfg) throw new Error(未找到环境配置: ${env}); return cfg; }关键在于业务代码里传的永远是orderPaid这种逻辑名而不是直接传 ID 字符串。这一层间接让换环境变成一个纯粹的环境变量动作人为失误的空间被压到最小。3.2 接口地址与模板类型错配前面提过一次这里从实操角度再强化一遍因为它太常见了。判断标准非常简单粗暴你的载体模板来源后台正确接口路径小程序小程序后台 - 订阅消息/cgi-bin/message/subscribe/send公众号公众号后台 - 模板消息/cgi-bin/message/template/send只要这两列不对齐40037 几乎必然出现。而且因为它不报接口不存在、不报参数错误只报模板无效特别容易把人往ID 复制错了的方向带。我在排查这类问题时有个习惯动作先把完整请求 URL 原样打印出来包括域名、路径、query string。很多次我发现路径里赫然写着subscribe/send但代码注释里写的是公众号模板消息推送问题一目了然。日志里只打 body 不打 URL是很多团队的通病对这类问题诊断极不友好。顺便说一个相关误区有些人为了兼容两种情况写了一堆 if-else 试图在两个接口间自动切换。我不建议这么干。这两套系统的语义本来就不同一个消耗订阅次数、一个走公众号关注关系混在一起只会让状态更难追踪。老老实实一个业务一个接口代码更清晰出问题也更好定位。3.3 复制粘贴带来的隐形字符这是最让人哭笑不得的一类。ID 明明是从后台复制的肉眼看着跟文档一模一样比对字符数也一样就是不认。原因通常是三种。第一是首尾空白复制的时候带上了空格或者换行符粘进代码里被引号包住肉眼看不出来。第二是不可见字符从某些编辑器或者聊天窗口里二次复制时混进来的零宽字符、制表符。第三是形近字符替换比如把数字0写成字母O把l写成1手抄过一次就会出现这种问题。排查手法很土但极其有效把 ID 的字符数和首尾字符打出来看。正常的小程序订阅消息模板 ID 是一串固定格式的字符长度大致在四十位上下包含字母、数字和连字符。你在代码里加一行诊断日志const tid config.templateIds.orderPaid; console.log(template_id 诊断:, { len: tid.length, head: JSON.stringify(tid.slice(0, 6)), tail: JSON.stringify(tid.slice(-6)), hasSpace: /\s/.test(tid) });如果head或tail打出来带引号包着的空格 abc或者len跟你预期的对不上问题当场就现形了。我的工程化处理是把 ID 在使用前做一次清洗和格式校验去掉所有空白字符校验长度和字符集不合格直接抛错并打日志不要发到微信那边去浪费一次请求。这样问题会在你自己的系统里暴露而不是伪装成一个 40037 让人摸不着头脑。function normalizeTemplateId(raw) { if (typeof raw ! string) throw new Error(template_id 必须是字符串); const cleaned raw.replace(/\s/g, ); if (!/^[A-Za-z0-9_-]{20,64}$/.test(cleaned)) { throw new Error(template_id 格式异常: len${cleaned.length}); } return cleaned; }3.4 参数位置放错URL 里还是 body 里这个坑不算常见但一旦踩了很折磨人。小程序的订阅消息接口access_token放在 URL 的 query 里template_id放在 POST body 里这一点大多数人不会错。但有人会把template_id也拼到 URL 上body 里不带服务端读不到这个字段就当成无效。同样的错法还有body 用了application/x-www-form-urlencoded编码但内容是 JSON 字符串或者 Content-Type 写了application/json却发了 form 数据。这类问题最终表现可能不是 40037有些情况会直接报 47003 参数错误但混合场景下确实会出现 40037。我的做法是统一用 JSON body明确设 Content-Type然后用 curl 做一次最小化验证确认请求结构没问题再去跑业务代码。curl 是最诚实的它不会帮你做任何隐式转换能跑通说明结构是对的。3.5 旧版模板消息接口已下线这个坑属于历史包袱型。小程序的早期确实提供过一条/cgi-bin/message/wxopen/template/send的模板消息接口后来被订阅消息全面取代。如果你在网上搜到的教程比较老、或者项目代码是从几年积累下来的老仓库里继承来的很可能还在调这条已经不服务的路径。表现可能有两种一种是直接报错说接口不存在另一种是在某些兼容处理下返回 40037。不管是哪种处理方式都一样——彻底检查请求路径凡是包含wxopen/template的都替换成subscribe/send同时确认模板是从订阅消息模板库选的。老模板消息的模板 ID 是另一套 ID 空间即使路径改对了、ID 没换照样报 40037这两件事必须一起改。顺带一提老项目迁移过来的时候data字段的结构也可能不同。旧版的 data 是{key:{value:xxx}}这样的形式新版订阅消息的 data 也是同样的嵌套结构但 key 变成了带类型前缀的字段名thing1、time2、character_string3这类。旧模板的 key 在新模板库里根本不存在所以迁移时务必对着新模板的字段列表重新映射一遍。4. 从零跑通一条订阅消息完整实操流程4.1 前置准备与配置清单在写任何代码之前我建议先把这些东西整齐地摆在桌面上一样都不能少项目说明来源appid小程序的唯一标识小程序后台 - 开发管理secret换取 access_token 的密钥小程序后台 - 开发管理template_id订阅消息模板标识小程序后台 - 订阅消息openid接收者的标识用户登录后由后端换取模板字段列表该模板包含哪些 key、什么类型模板详情页一次真实授权用户在小程序里点过授权前端调用 wx.requestSubscribeMessage特别强调最后一项。订阅消息的发送前提是用户在小程序内点击过一次授权你在前端调用wx.requestSubscribeMessage({ tmplIds: [你的模板ID] })用户点了允许系统才记下这次授权你的后端才能发一条。很多人卡在 43101用户拒绝接收上本质是没理解这个机制。但如果你现在报的是 40037说明连授权这一关都还没走到——服务端在读模板 ID 的时候就把它毙了。还有一个隐性的准备工作服务器出口 IP 白名单。如果你的小程序后台开了IP 白名单限制而你的服务器 IP 不在名单里换 access_token 就会失败进而引发一连串错误。这个跟 40037 没直接关系但经常混在一起出现联调时容易互相干扰建议一开始就配好。4.2 获取 access_token 的正确姿势access_token 是所有服务端接口的通行证有效期两小时需要缓存复用。最常见的错误是每次发消息都去换一个新的 token这会造成两个后果一是浪费调用次数每天的换取次数是有上限的二是新 token 生成会让旧 token 在短时间内仍有效但如果调用过于频繁可能出现 token 互相覆盖的混乱现象。标准做法是缓存提前刷新容错重取。用 Node.js 写个最朴素的实现// token.js import axios from axios; const API https://api.weixin.qq.com; let cache { token: , expireAt: 0 }; async function fetchToken(appid, secret) { const { data } await axios.get(${API}/cgi-bin/token, { params: { grant_type: client_credential, appid, secret }, timeout: 8000 }); if (data.errcode) { throw new Error(换取 token 失败: ${data.errcode} ${data.errmsg}); } return { token: data.access_token, expireAt: Date.now() (data.expires_in - 300) * 1000 // 提前 5 分钟过期 }; } export async function getAccessToken(appid, secret) { if (cache.token Date.now() cache.expireAt) return cache.token; cache await fetchToken(appid, secret); return cache.token; } export function clearToken() { cache { token: , expireAt: 0 }; }提前五分钟过期的设计意图很简单避免在 token 即将失效的那一瞬间被多个请求同时命中导致部分成功部分失败。clearToken则用于在收到 40001 / 42001token 失效时强制刷新重试一次。这套逻辑不复杂但能省掉大量偶发的诡异问题。4.3 组装请求体每个字段的作用订阅消息的请求体结构如下我把每个字段的作用和常见坑一起标出来{ touser: 用户的 openid, // 必须是本小程序的 openid别的号的 openid 无效 template_id: 你的模板 ID, // 必须来自本小程序订阅消息模板库 page: pages/order/detail?id123, // 点击跳转的小程序页面不带前导斜杠 data: { thing1: { value: 订单支付成功 }, character_string2: { value: 202401010001 }, time3: { value: 2024年01月01日 12:00 } }, miniprogram_state: formal, // developer / trial / formal lang: zh_CN }几个必须说清楚的细节page字段不要以/开头也不要带.html后缀直接写pages/xxx/xxx加 query 参数。写错了不会导致 40037但会导致用户点击后跳转失败属于报错消失但体验崩了的隐形问题。data里的 key 必须与模板详情页上列出的字段 key完全一致包括后缀数字。模板里如果是thing1你写成thing或thing2都会报 47003。而字段的类型前缀决定了内容的格式要求thing是短文本长度有限制time必须是可识别的时间格式character_string是字符串型适合订单号number是纯数字amount是金额。类型对不上也会报 47003而不是 40037所以这两个错误码经常成对出现——先报 40037你改对了 ID紧接着报 47003。miniprogram_state决定这条消息点击后跳到哪个版本的小程序。开发阶段用developer或trial线上用formal。这个字段填错不会报错但会让你以为消息没发出去——实际上发出去了只是跳到了另一个版本。4.4 三段可直接运行的发送代码先看 Node.js 版本这是最常见的服务端场景// sendSubscribeMsg.js import axios from axios; import { getAccessToken, clearToken } from ./token.js; const API https://api.weixin.qq.com; export async function sendSubscribeMsg({ appid, secret, openid, templateId, page, data, state formal }) { const url ${API}/cgi-bin/message/subscribe/send; async function doSend() { const token await getAccessToken(appid, secret); const { data: res } await axios.post(url, { touser: openid, template_id: templateId, page, data, miniprogram_state: state, lang: zh_CN }, { params: { access_token: token }, timeout: 8000, headers: { Content-Type: application/json } }); return res; } let res await doSend(); // token 失效刷新后重试一次 if ([40001, 42001, 40014].includes(res.errcode)) { clearToken(); res await doSend(); } if (res.errcode ! 0) { // 关键把 template_id 一起打进日志40037 才有据可查 throw new Error(发送失败 errcode${res.errcode} errmsg${res.errmsg} template_id${templateId}); } return res; }Python 版本用requests更直观import time import requests API https://api.weixin.qq.com _cache {token: , expire_at: 0} def get_token(appid, secret): if _cache[token] and time.time() _cache[expire_at]: return _cache[token] r requests.get(f{API}/cgi-bin/token, params{ grant_type: client_credential, appid: appid, secret: secret }, timeout8) d r.json() if errcode in d: raise RuntimeError(ftoken 失败: {d[errcode]} {d[errmsg]}) _cache[token] d[access_token] _cache[expire_at] time.time() d[expires_in] - 300 return _cache[token] def send_subscribe_msg(appid, secret, openid, template_id, page, data, stateformal): token get_token(appid, secret) payload { touser: openid, template_id: template_id, page: page, data: data, miniprogram_state: state, lang: zh_CN } r requests.post( f{API}/cgi-bin/message/subscribe/send, params{access_token: token}, jsonpayload, timeout8 ) res r.json() if res.get(errcode) ! 0: raise RuntimeError(f发送失败 errcode{res.get(errcode)} errmsg{res.get(errmsg)} template_id{template_id}) return resJava 版本用 OkHttp把关键点也标出来import okhttp3.*; import com.fasterxml.jackson.databind.ObjectMapper; import java.util.Map; public class SubscribeSender { private static final String API https://api.weixin.qq.com; private final OkHttpClient client new OkHttpClient.Builder() .connectTimeout(java.time.Duration.ofSeconds(8)) .readTimeout(java.time.Duration.ofSeconds(8)) .build(); private final ObjectMapper mapper new ObjectMapper(); public String send(String token, String openid, String templateId, String page, MapString, Object data) throws Exception { MapString, Object body Map.of( touser, openid, template_id, templateId, page, page, data, data, miniprogram_state, formal, lang, zh_CN ); Request req new Request.Builder() .url(API /cgi-bin/message/subscribe/send?access_token token) .post(RequestBody.create( mapper.writeValueAsBytes(body), MediaType.parse(application/json; charsetutf-8))) .build(); try (Response resp client.newCall(req).execute()) { String text resp.body() null ? : resp.body().string(); if (text.contains(\errcode\:40037)) { throw new IllegalStateException(模板 ID 无效检查来源与后台是否一致: templateId); } return text; } } }三段代码的共同点在于失败时必须把 template_id 带进日志。这是我踩过坑之后加的硬性要求因为大多数线上日志只记了 errcode 和 errmsg等你去查的时候根本不知道当时用的是哪个 ID只能靠猜。4.5 用 curl 做最小化验证业务代码里夹着各种封装、各种中间件排查问题时容易看不清真相。我习惯先用 curl 打一枪确认最基础的调用链路是通的# 第一步换 token curl -s https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid你的APPIDsecret你的SECRET # 第二步发一条订阅消息 curl -s -X POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token上一步拿到的TOKEN \ -H Content-Type: application/json \ -d { touser: 用户的OPENID, template_id: 你的模板ID, page: pages/index/index, data: { thing1: { value: 测试内容 }, time2: { value: 2024年01月01日 12:00 } }, miniprogram_state: developer, lang: zh_CN }如果 curl 返回 0说明 ID、token、结构全对问题出在你的业务代码里配置读取错了、字符串被截断了、环境变量没注入。如果 curl 也返回 40037那问题一定在这串 ID 本身跟前端、跟业务逻辑无关可以放心地只盯着一件事查。这个二分法能极大缩短排查时间我很推荐养成先 curl 后代码的习惯。5. 报错码联动排查速查表5.1 40037 周边的常客单看一个 40037 信息量有限但把它和前后脚出现的错误码放一起看往往能直接锁定方向。下面这几个是我在实际工作中遇到频率最高的邻居错误码含义与 40037 的关系40037无效的模板 ID本文主角ID 来源/生命周期/格式问题47003参数不合法常紧随 40037 之后ID 修对了但字段 key 或类型不对43101用户拒绝接收或已无订阅次数ID 对了、字段对了但用户没授权或次数用光41030page 路径不正确ID 对了跳转页写错了40003无效的 openid用户标识不是本小程序的40001 / 42001access_token 失效需要刷新重试与 ID 无关45009接口调用超限频控问题与 ID 无关40013无效的 appid配置整体错乱的前兆看这张表的正确姿势是从 40037 出发按顺序往后推。先把 ID 修对再看有没有冒出 47003字段修好之后再看 43101用户订阅问题解决后再看 41030 跳转。这条链路是一环扣一环的新手最容易犯的错是一次性把所有环节都改一遍结果报错变了却不知道是哪一处改动起的作用。一次只改一个变量是我做联调时最守的规矩。5.2 现象到病根的反查表有时候你没有机会看日志只有一句消息没收到的口头反馈。这时候可以按现象反查现象最可能的原因快速验证方式接口返回 40037ID 来源错误或已失效后台模板列表核对 ID 是否存在接口返回 0 但用户没收到用户已用完订阅次数查该用户近期授权记录接口返回 0 但点击跳转 404page 路径写错或页面未发布用 developers 版手动跳一次测试环境正常线上全挂环境配置串号打印线上实际使用的 template_id昨天正常今天全挂模板被下架或回收后台确认模板状态偶发失败比例很低token 刚好过期或频控看是否集中在整点前后这张表我建议直接贴进团队的排查文档里。因为 40037 这类问题往往是在深夜或者版本发布窗口出现的当事人脑子不太清醒有一张照方抓药的表格能省很多事。5.3 让问题在用户投诉之前暴露等用户来问为什么我没收到通知说明你的监控是缺位的。我的做法是在发送层加三个观测点。第一是发送前置校验。前面那个normalizeTemplateId就是干这个的格式不对直接抛错连请求都不发。第二是发送结果分类统计把 errcode 按天聚合40037 单独一个指标一旦非零立刻告警。第三是模板健康巡检每天定时用内部测试账号给每个模板发一条失败就通知负责人。这三个观测点加起来代码量很小但能把模板静默失效这类事故的发现时间从用户投诉提前到当晚。我经历过一次模板被回收的事故就是因为有巡检凌晨两点告警值班同事确认后切了备用模板第二天早上业务方甚至都不知道出过问题。6. 踩坑记录与工程化建议6.1 模板 ID 永远不要硬编码在业务逻辑里这是我所有建议里最硬的一条。业务代码里直接写const tpl ABCdef123...的写法短期看省事长期看是负债。原因有三个环境切换要改代码、模板更换要改代码、多个模板要管理时无从下手。正确姿势是逻辑名 配置映射。业务层只说我要发一条订单支付成功通知由配置层决定这次用的是哪个 ID。这样模板换了只改配置环境切换只改环境变量代码本身零改动。再进一步把模板定义做成结构化数据连字段映射一起管起来// templates.js export const TEMPLATES { orderPaid: { id: process.env.TPL_ORDER_PAID, page: pages/order/detail, fields: { title: thing1, orderNo: character_string2, paidTime: time3, amount: amount4 } } }; export function buildData(logicalName, bizData) { const tpl TEMPLATES[logicalName]; if (!tpl) throw new Error(未定义的模板: ${logicalName}); const data {}; for (const [bizKey, tplKey] of Object.entries(tpl.fields)) { data[tplKey] { value: String(bizData[bizKey] ?? ) }; } return { templateId: tpl.id, page: tpl.page, data }; }这一层抽象带来的好处在模板变更时会集中爆发出来模板字段改了一个你只需要改fields那几行所有调用方自动跟着变不用去十几个业务文件里搜字符串。6.2 发送失败要有兜底不要一次失败就丢消息消息推送是典型的最终成功即可场景微信侧偶尔的抖动、token 恰好过期、频控瞬时触发都会导致单次失败。如果业务代码是发一次失败就记个日志拉倒你会发现消息送达率大概在 95% 左右剩下 5% 的用户永远收不到。我的做法是区分可重试与不可重试。40001、42001、45009 这类是典型可重试的退避几秒后重试一次通常就好40037、47003 这类是配置或参数错误重试一万次也一样必须进人工告警队列。const RETRYABLE new Set([40001, 42001, 40014, 45009, -1]); async function sendWithRetry(params, maxTry 2) { let lastErr; for (let i 0; i maxTry; i) { try { return await sendSubscribeMsg(params); } catch (e) { lastErr e; const code Number((String(e.message).match(/errcode(-?\d)/) || [])[1]); if (!RETRYABLE.has(code)) break; await new Promise(r setTimeout(r, 1000 * (i 1))); } } // 不可重试或重试耗尽进异步补偿队列 await pushToCompensationQueue(params, lastErr.message); throw lastErr; }补偿队列可以是数据库表可以是消息队列主题甚至一开始就是个定时扫的日志表。形式不重要重要的是别让消息悄无声息地死掉。6.3 订阅次数是一笔要记的账订阅消息是一次性消费的用户点一次授权你才能发一条。这意味着你的业务系统必须自己维护一份订阅余额否则就会出现系统觉得该发微信说用户没授权的 43101。我的做法是在用户授权成功的回调里往数据库写一条订阅记录包含用户标识、模板逻辑名、剩余次数、最近授权时间。发送时先扣减本地余额再调微信接口调用成功则确认扣减失败则回滚。这套账本机制听起来麻烦但它能让你在发消息之前就知道这个人还能不能收避免无效请求和错误的静默失败。还有个实操细节一次性订阅的授权是可以累积的。用户点三次授权你就能发三条。但很多前端只在关键业务节点弹一次授权弹窗导致余额经常是零。我建议在用户活跃度高的页面比如个人中心、订单列表做一次批量订阅引导把多个模板一次性授权掉能显著提升后续消息的触达率。最后分享一个我自己踩过的坑早期我在做一个审核结果通知模板 ID 配在配置中心里某次发布时配置中心的 key 少写了一个字母tpl_audit_resul读取不到就用了个空字符串默认值结果全线报 40037。后来我加了一条启动自检所有模板 ID 在服务启动时必须非空且格式合法否则直接启动失败。听起来激进但比起上线后静默失败启动时崩掉反而是最温柔的失败方式。
