微信小程序调用手册
用登录 code 校验小程序用户身份
把 wx.login 的临时 code 交给服务端换取 OpenID 和会话密钥，区分微信会话和自己的业务登录态。
← 返回平台功能接入准备
- 已绑定小程序开发成员，持有该小程序 AppID 与 AppSecret。
- 在小程序客户端调用 wx.login，把 success 回调的 code 经自己的 HTTPS 服务发送到后台；不要把 AppSecret 放进小程序。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。
WX_MINI_APP_ID- 自有小程序 AppID，不是公众号 AppID。
WX_MINI_APP_SECRET- 同一小程序的 AppSecret，只保存在服务端。
WX_MINI_LOGIN_CODE- 必须来自当前小程序 wx.login 的临时登录凭证，不是手机号 code。
export WX_MINI_APP_ID='wx_replace_with_your_miniprogram_appid'
export WX_MINI_APP_SECRET='replace_with_your_miniprogram_secret'
export WX_MINI_LOGIN_CODE='replace_with_fresh_wx_login_code'以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件，再在同一终端执行。
调用步骤
- 01
在同一终端设置小程序凭证和新取得的 WX_MINI_LOGIN_CODE；code 只能消费一次。
- 02
保存下方 Node.js 代码为 request.mjs 并运行 node request.mjs。
- 03
成功后在自己的后台用 OpenID 关联业务会话，session_key 仅留服务端；本例脚本不实现完整业务会话系统。
调用 01
交换登录凭证
服务端构造编码后的查询参数，不向客户端暴露密钥；代码只输出必要身份信息。
GET
https://api.weixin.qq.com/sns/jscode2session?appid=${WX_MINI_APP_ID}&secret=${WX_MINI_APP_SECRET}&js_code=${WX_MINI_LOGIN_CODE}&grant_type=authorization_code参数说明
参数表可左右滑动，查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
appidQuery | string必填 | 当前小程序 AppID。 |
secretQuery | string必填 | 同一小程序 AppSecret，仅服务端使用。 |
js_codeQuery | string必填 | wx.login 返回的一次性 code。 |
grant_typeQuery | string必填 | 固定 authorization_code。 |
调用代码
替换示例 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 url = new URL('https://api.weixin.qq.com/sns/jscode2session');
url.search = new URLSearchParams({
appid: required('WX_MINI_APP_ID'), secret: required('WX_MINI_APP_SECRET'),
js_code: required('WX_MINI_LOGIN_CODE'), grant_type: 'authorization_code',
}).toString();
const result = await request(url);
if (!result.openid || !result.session_key) throw new Error('响应缺少登录身份或会话密钥');
// session_key 只留服务端，不返回小程序，也不输出到日志。
// 正式服务把它与自己的业务会话关联，给前端返回自己的登录态。
console.log(JSON.stringify({ openid: result.openid,
...(result.unionid ? { unionid: result.unionid } : {}),
session_key_received: true }, null, 2));
返回示例
虚构结构示意，非实测。unionid 仅在绑定等条件满足时返回，不保证存在。 以下为结构示意，非本站实测结果。
{
"openid": "OPENID_EXAMPLE",
"session_key": "BASE64_SESSION_KEY_EXAMPLE",
"unionid": "OPTIONAL_UNIONID_EXAMPLE"
}常见错误与排查
40029code 无效、过期或已消费。- 重新在同一小程序调用 wx.login，避免重放旧 code。
40226登录被平台风控拦截。- 按官方诊断流程检查，不通过重复请求绕过。
40013 / 40125账号或密钥不正确。- 核对小程序 AppID、AppSecret 与账号类型，避免混用公众号凭证。
45009 / 45011日配额或调用频率受限。- 按官方后台额度控制请求，不重复强制刷新或无限重试。
调用注意
- 不要缓存登录 code 重复兑换，不把 session_key 下发到客户端或写入业务日志。
注意事项
- OpenID 属于当前小程序，不能拿其他小程序的标识代替。
- 服务端自定义登录态、过期与撤销由自己的应用实现，本页仅演示微信接口调用。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01登录流程与 session_key 边界核验日期 2026-10-15
- 02code2Session 参数及错误码核验日期 2026-10-15