微信小程序调用手册
获取并复用小程序后台凭证
普通 stable_token 模式取得后台 token,按实际剩余有效期维护,避免各进程强刷。
← 返回平台功能接入准备
- 拥有同一小程序 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 的终端。按调用步骤保存代码文件,再在同一终端执行。
调用步骤
- 01
配置 WX_MINI_APP_ID、WX_MINI_APP_SECRET,保存下方 Node 代码为 token.mjs。
- 02
在自己的终端运行 export WX_MINI_ACCESS_TOKEN="$(node token.mjs)",不把输出粘贴到本站。
- 03
生产服务统一缓存 token,记录返回 expires_in 并提前刷新;普通调用可能返回现有 token 的剩余有效期。
调用 01
普通模式获取 stable_token
force_refresh 固定 false,本例不使现有业务凭证主动失效。
POST
https://api.weixin.qq.com/cgi-bin/stable_token请求头
Content-Typeapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
grant_type请求体 | string必填 | 固定 client_credential。 |
appid请求体 | string必填 | 当前小程序 AppID。 |
secret请求体 | string必填 | 当前小程序 AppSecret。 |
force_refresh请求体 | boolean可选 | 本例 false;true 会使上次凭证失效。 |
调用代码
替换示例 ID 与请求体内容后运行。
// 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。 以下为结构示意,非本站实测结果。
{
"access_token": "BACKEND_ACCESS_TOKEN_EXAMPLE",
"expires_in": 345
}常见错误与排查
40013 / 40125账号或密钥不正确。- 核对小程序 AppID、AppSecret 与账号类型,避免混用公众号凭证。
40164服务端出口 IP 不在白名单。- 在官方后台核对实际出口地址及该账号的 API IP 白名单。
45009 / 45011日配额或调用频率受限。- 按官方后台额度控制请求,不重复强制刷新或无限重试。
调用注意
- 与旧 getAccessToken 凭证互相隔离;普通模式与强制刷新不要混为一谈。
- 普通请求限频与强刷限制分别计算,具体额度按当前文档和账号核对。
注意事项
- token 不是用户登录态,也不是 session_key。
- 示例只输出 token 以便本机赋值;正式缓存还需保存有效期并进行并发刷新控制。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01服务端 API 安全配置核验日期 2026-10-15
- 02getStableAccessToken核验日期 2026-10-15
