微信小程序调用手册

获取并复用小程序后台凭证

普通 stable_token 模式取得后台 token,按实际剩余有效期维护,避免各进程强刷。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 拥有同一小程序 AppID 与 AppSecret,已核对服务端 IP 白名单。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

WX_MINI_APP_ID
自有小程序 AppID,不是公众号 AppID。
WX_MINI_APP_SECRET
同一小程序的 AppSecret,只保存在服务端。
终端
export WX_MINI_APP_ID='wx_replace_with_your_miniprogram_appid'
export WX_MINI_APP_SECRET='replace_with_your_miniprogram_secret'

以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件,再在同一终端执行。

调用步骤

  1. 01

    配置 WX_MINI_APP_ID、WX_MINI_APP_SECRET,保存下方 Node 代码为 token.mjs。

  2. 02

    在自己的终端运行 export WX_MINI_ACCESS_TOKEN="$(node token.mjs)",不把输出粘贴到本站。

  3. 03

    生产服务统一缓存 token,记录返回 expires_in 并提前刷新;普通调用可能返回现有 token 的剩余有效期。

调用 01

普通模式获取 stable_token

force_refresh 固定 false,本例不使现有业务凭证主动失效。

POSThttps://api.weixin.qq.com/cgi-bin/stable_token

请求头

Content-Type
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
grant_type请求体string必填固定 client_credential。
appid请求体string必填当前小程序 AppID。
secret请求体string必填当前小程序 AppSecret。
force_refresh请求体boolean可选本例 false;true 会使上次凭证失效。

调用代码

替换示例 ID 与请求体内容后运行。

Node.js
// Node.js 22+,保存为 request.mjs,环境变量在同一终端设置。
const required = name => {
  const value = process.env[name];
  if (!value) throw new Error('缺少环境变量 ' + name);
  return value;
};
async function request(url, body) {
  const response = await fetch(url, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    redirect: 'error', signal: AbortSignal.timeout(20000),
  });
  const raw = await response.text();
  if (!response.ok) throw new Error('HTTP ' + response.status);
  let result;
  try { result = JSON.parse(raw); } catch { throw new Error('平台未返回有效 JSON'); }
  if (!result || typeof result !== 'object' || Array.isArray(result)) throw new Error('响应结构不正确');
  if (Object.hasOwn(result, 'errcode') && result.errcode !== 0) {
    throw new Error('微信业务错误 ' + result.errcode + ': ' + (result.errmsg || ''));
  }
  return result;
}
const result = await request('https://api.weixin.qq.com/cgi-bin/stable_token', {
  grant_type: 'client_credential', appid: required('WX_MINI_APP_ID'),
  secret: required('WX_MINI_APP_SECRET'), force_refresh: false,
});
if (!result.access_token || !Number.isFinite(result.expires_in) || result.expires_in <= 0) {
  throw new Error('平台未返回有效后台 token 或有效期');
}
// 仅输出 token,便于在自己终端中赋值;不要粘贴到公开页面。
// 生产服务应集中存储并按返回 expires_in 提前刷新,不反复请求。
console.log(result.access_token);

返回示例

结构示意,非实测。expires_in 是当前凭证的剩余有效秒数,不应每次硬编码为 7200。 以下为结构示意,非本站实测结果。

JSON
{
  "access_token": "BACKEND_ACCESS_TOKEN_EXAMPLE",
  "expires_in": 345
}

常见错误与排查

40013 / 40125账号或密钥不正确。
核对小程序 AppID、AppSecret 与账号类型,避免混用公众号凭证。
40164服务端出口 IP 不在白名单。
在官方后台核对实际出口地址及该账号的 API IP 白名单。
45009 / 45011日配额或调用频率受限。
按官方后台额度控制请求,不重复强制刷新或无限重试。

调用注意

  • 与旧 getAccessToken 凭证互相隔离;普通模式与强制刷新不要混为一谈。
  • 普通请求限频与强刷限制分别计算,具体额度按当前文档和账号核对。

注意事项

  • token 不是用户登录态,也不是 session_key。
  • 示例只输出 token 以便本机赋值;正式缓存还需保存有效期并进行并发刷新控制。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
    服务端 API 安全配置核验日期 2026-10-15
  2. 02
    getStableAccessToken核验日期 2026-10-15

微信小程序的其他调用手册

← 返回微信小程序的全部功能