编程 微信第三方平台五级凭据链排障:先看 ticket 落库时间,再查签名

2026-11-21 00:04:27

微信第三方平台五级凭据链排障:先看 ticket 落库时间,再查签名

第三方平台(服务商)的代调用报错,绝大多数不是加解密或签名问题,而是链条上某一级凭据过期、丢失或传错。这条链上的六个凭据由五次换取动作连接起来,任何一级断开,最终都会变成 40001 invalid credential 这类含糊的报错。下面按从源头到末端、再从时间戳到签名的顺序梳理。

官方文档:

五级链与各自的有效期

凭据有效期换取方式
component_verify_ticket12 小时微信每 10 分钟 POST 推送
component_access_token2 小时ticket + 平台 appid/secret
pre_auth_code1800 秒component_access_token
authorization_code600 秒(回调 expires_in=600)商家扫码授权后回调返回
authorizer_refresh_token长期,商家不解除授权就一直有效authorization_code 换取
authorizer_access_token7200 秒authorizer_refresh_token 换取

排障时只需先问一句:出问题的是哪一级,它现在几点入库的。

component_verify_ticket:收下来就直接落库

第三方平台创建审核通过后,微信服务器会每 10 分钟向「授权事件接收 URL」POST 一次 ticket。推送参数里 InfoType 固定为 component_verify_ticket,CreateTime 是秒级时间戳,ComponentVerifyTicket 解密后是 XML。接收端处理完直接返回字符串 success,不要包 JSON、不要加额外字段,返回体不对会被当成接收失败。

ticket 的有效期是 12 小时,比 component_access_token 的 2 小时长。这个差异是兜底设计的依据:保存最近一次可用的 ticket,在 component_access_token 过期前都可以拿它去更新,避免因为某一轮推送接收失败就彻底无法换取 token。

因此不要用「新值覆盖旧值」的逻辑,而应保留最近可用的那条并记录接收时间。

第一现场:拉不到 component_access_token

遇到 api_component_token 失败,先查 ticket 的落库时间,不要先去翻签名代码。

多实例部署时,如果 ticket 只保存在进程内存,重启一次就全丢;新实例没收到推送前又拿不到 token,整个平台的代调用会集体报 40001。这类故障的特征是:所有商家同时失败,重启后一段时间自行恢复,随后又复发。

curl -s -X POST "https://api.weixin.qq.com/cgi-bin/component/api_component_token" \
  -H "Content-Type: application/json" \
  -d '{"component_appid":"wxCOMPONENT_APPID","component_appsecret":"SECRET","component_verify_ticket":"TICKET"}'

拿库里的 receive_time 和当前时间比对,超过 12 小时基本可以确定是推送没收到或没落库,再去查回调 URL 是否可达、返回体是否合规。

pre_auth_code 与授权链接参数

pre_auth_code 有效期 1800 秒,用于生成扫码授权二维码或链接,属于一次性凭据,不要缓存起来复用给多个商家。

自建授权链接的必填参数是 component_appid、pre_auth_code、redirect_uri、auth_type,可选 biz_appid、category_id_list。auth_type 取值:

  • 1 仅公众号
  • 2 仅小程序
  • 3 公众号和小程序都展示
  • 4 小程序推客
  • 5 视频号
  • 6 全部
  • 8 带货助手

biz_appid 用于指定唯一授权账号,指定后只有该 appid 的管理员能完成授权。它和 auth_type 冲突时 biz_appid 优先级更高:例如传了 auth_type=1 但 biz_appid 是小程序,会按 auth_type=2 处理。这类「参数写了但没生效」的问题,基本都是这里。

H5 链接形态:

https://open.weixin.qq.com/wxaopen/safe/bindcomponent?action=bindcomponent&no_scan=1&component_appid=xxxx&pre_auth_code=xxxxx&redirect_uri=xxxx&auth_type=xxx&biz_appid=xxxx#wechat_redirect

平台未全网发布时,还要先把测试公众号或小程序加入「授权测试公众号/小程序列表」,否则扫码端直接拒绝。

authorization_code 换 refresh_token

商家授权后回跳 redirect_url?auth_code=xxx&expires_in=600,这个 code 只有 600 秒。要在窗口内用 component_access_token 调 api_query_auth 换取 authorizer_refresh_token 和授权信息。

返回的 func_info 是商家实际勾选的权限集 id 列表。公众号和小程序可以只授权部分权限,所以权限判断要以接口返回为准,不能按自己页面声明的权限集算。否则会出现「接口报无权限但用户说授权了」的拉扯。

refresh_token is invalid 的两个成因

报这个错时按顺序排查,不要一开始就怀疑商家解绑。

第一,检查请求参数里的 authorizer_refresh_token 是不是 null。少数开发者在调 api_authorizer_token 时字段名写错或取值漏了,微信侧收到空值,返回的却是「token 无效」。用开放平台 API 调试工具看微信侧实际收到的请求参数,一分钟就能排除。

第二,确认传了值仍然报错,说明 token 真的失效了。此时调 getAuthorizerList 拉回所有已授权账号的 refresh_token。如果列表里某个账号的 refresh_token 返回空,说明它授权过但当时没及时换 token(比如回调处理超时、服务重启丢了上下文),需要补调 getAuthorizerRefreshToken 换取。如果授权码本身已经过期,就只能触发更新授权,让商家重新扫码,没有服务端补救途径。

另外,authorizer_refresh_token 长期有效的前提是商家不解除授权;一旦解绑后重新授权,refresh_token 会变,旧值直接失效,落库时整行覆盖。

IP 白名单:token 都对还报错,先看出口 IP

所有第三方平台 API 调用都校验调用者 IP,只有在第三方平台白名单 IP 列表内的 IP 才能合法调用,其余一律拒绝。

这一条在服务迁移时最容易踩:服务从自建机房搬到云上,出站走 NAT 网关的弹性 IP,白名单还停留在老地址,于是 token 全部正常、权限集也正常,但每个接口都失败。排查时先核对当前机器的公网出口 IP(curl ifconfig.me 之类),再去开放平台后台比对白名单,别在代码里找。

错误码只认文档写法

  • 40001:invalid credential,access_token is invalid or not latest
  • 40013:invalid appid
  • 89000:account has bound open(开放平台账号已绑定)
  • 89001:not same contractor(主体不同)

注意后两个属于开放平台账号绑定接口(/cgi-bin/open/create、/bind、/unbind、/get),不在 ticket-token 这条链上。看到 89000/89001 却去翻刷新令牌的代码,方向就错了。

落库与缓存

ticket 和 refresh_token 都必须持久化,且多实例共享。最小表结构:

CREATE TABLE wx_component_ticket (
  app_id       VARCHAR(64)  NOT NULL COMMENT '第三方平台 appid',
  ticket       VARCHAR(512) NOT NULL,
  create_time  INT          NOT NULL COMMENT '微信推送的 CreateTime(秒)',
  receive_time INT          NOT NULL COMMENT '本地落库时间(秒)',
  PRIMARY KEY (app_id),
  KEY idx_receive (receive_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wx_authorizer_token (
  authorizer_appid  VARCHAR(64)  NOT NULL,
  refresh_token     VARCHAR(512) NOT NULL,
  access_token      VARCHAR(512) DEFAULT NULL,
  access_expire_at  INT          DEFAULT NULL COMMENT '绝对过期时间(秒)',
  update_time       INT          NOT NULL,
  PRIMARY KEY (authorizer_appid)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

token 缓存建议按绝对过期时间存,刷新提前量留 5–10 分钟,不要等 expires_in 走完再换。多个实例同时发现过期会并发刷新,加个分布式锁或让单个实例负责刷新、其他实例读缓存,能避免互相把对方的 token 顶掉——access_token is not latest 这类报错往往就是这么来的。

这条链上的故障,八成出在「凭据存在哪」和「它几点入库」两个问题上,跟加解密关系不大。把 ticket 和 refresh_token 放进共享存储,把接收时间一并记下来,剩下的基本是查表。

推荐文章

程序员茄子在线接单