跳到主要内容
api工厂
小程序

小程序登录态设计:wx.login、code2Session、token 刷新与多端统一

api工厂资讯栏目 约 7 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行:小程序登录的标准链路是——前端 wx.login 拿临时 code,服务端调 code2Session 换取 openid 与 session_key,再签发自己的业务 token 返回前端;后续请求统一携带 token,过期时静默重新 wx.login 换新 token 并重放请求。三条铁律:code 一次性使用、session_key 与 AppSecret 绝不下发到前端、业务登录态与微信凭证解耦。把这三条守住,登录体系就既安全又顺滑。

一、先分清三种凭证

很多团队把 token 混为一谈,排查问题时越查越乱。实际上是三个完全不同的东西:

凭证谁签发用途有效期与注意
code微信客户端 wx.login服务端换 openid 的临时票据一次性,几分钟内失效
session_key微信服务端 code2Session 返回解密手机号等开放数据随用户使用微信刷新,只存服务端
access_token微信服务端接口凭证接口服务端调微信开放接口约两小时,需中控缓存,与用户无关
业务 token你自己的服务端标识用户登录态自定有效期,前端存储携带

「api工厂」帮助中心专门有一篇「token、X-TOKEN、access_token 的区别」讲这组概念:access_token 是平台与微信之间的接口凭证,开发者根本不用碰;X-TOKEN 是前端请求头里携带的用户业务 token。文档入口:https://www.it120.cc/help/index.html 。

二、标准登录链路

  1. 前端 wx.login 获取 code,传给服务端登录接口;
  2. 服务端用 appid、secret、code 调 code2Session,得到 openid、unionid(满足条件时)与 session_key;
  3. 按 openid 查用户表,不存在则静默注册;
  4. 签发业务 token(JWT 或不透明随机串加服务端存储均可),返回前端;
  5. 前端写入 storage,之后所有请求在 header 携带。
js
async function silentLogin() {
  const { code } = await wx.login();
  const res = await request('/auth/login', { code });
  wx.setStorageSync('token', res.token);
  return res.token;
}

安全红线:AppSecret 只能放服务端环境变量,小程序包可被解包,任何写进前端的密钥都等于公开;openid 也不能由前端直接提交作为身份依据,必须由服务端用 code 换取,否则可被伪造。session_key 用于解密 getPhoneNumber 等开放数据,同样只留在服务端,且微信会在用户重新登录等时机使其失效,解密失败时应引导重新 wx.login。

三、token 过期:静默刷新与请求重放

体验最差的做法是 token 一过期就把用户踢回登录页。正确姿势是在请求封装层统一处理:收到 401(或业务码标识登录失效)时,先静默 wx.login 换新 token,成功后重放原请求,失败再引导用户主动登录。两个工程细节必须处理:

  1. 并发去重:页面同时发五个请求都收到 401,只能触发一次刷新,其余请求挂起等待同一个 Promise,否则会连发五次 wx.login 与登录接口。
  2. 重放上限:每个请求最多重放一次,避免服务端异常时无限循环。
js
let refreshing = null;
async function handleExpired() {
  if (!refreshing) {
    refreshing = silentLogin().finally(() => { refreshing = null; });
  }
  return refreshing;
}

token 有效期建议按业务风险定:内容浏览类可以数天,交易类短一些并配合敏感操作二次校验。服务端要支持主动吊销(改密码、注销、风控命中),不要只依赖自然过期。

四、手机号登录与账号打通

纯 openid 登录是「设备身份」,用户换微信号或跨端就找不回账号。要沉淀会员资产,需要手机号或 unionid 做账号主键:

  • 微信侧用 button open-type 为 getPhoneNumber 获取手机号 code,服务端调微信接口换取真实手机号,绑定到当前用户;
  • 同一开放平台主体下的小程序、公众号、App 通过 unionid 识别同一用户;
  • 短信验证码登录作为兜底通道,覆盖 H5 与 App 端。

这套体系自建要写不少代码。「api工厂」(https://www.it120.cc/)把微信授权登录、手机号登录、短信验证码、会员积分成长值做成了现成能力:后台开通后,小程序端用 apifm-wxapi(npm 安装,WXAPI.init('subDomain') 初始化)调登录接口即可拿到 token,之后请求头带 X-TOKEN,统一返回 code、data、msg,code 为 0 即成功。用户体系、积分、优惠券、订单天然挂在同一个账号下,不用自己设计表结构与绑定逻辑。

五、多端统一:一套账号,多个壳

业务往往不止微信小程序:还有抖音小程序、支付宝小程序、H5、App。统一的关键不在前端,而在服务端账号模型:

  1. 用户表以手机号或内部 uid 为主键,微信 openid、抖音 openid、支付宝 user_id 作为「第三方身份」子表,一对多绑定;
  2. 各端登录接口入参不同(code 来源不同),但出参统一为同一套业务 token;
  3. token 校验、刷新、吊销逻辑全端复用,前端只是换壳。

用 uni-app 做多端时,「api工厂」提供 apifm-uniapp 与 apifm-ttapi(抖音)等配套 SDK,接口风格与 apifm-wxapi 一致,登录、商品、订单代码基本可以跨端复用,只需替换各端的授权登录入口。真实的多端商城与会员案例可参考 https://www.it120.cc/cases.html 。

六、登录态自查清单

  • code 是否只在服务端使用且一次一换;
  • AppSecret、session_key 是否完全不出现在前端与仓库;
  • 401 是否静默刷新并重放,并发是否去重;
  • 是否有手机号或 unionid 打通账号,支持注销与吊销;
  • 多端是否共用同一账号模型与 token 规范。

登录是几乎所有业务的入口,值得在架构期一次做对。微信侧接口行为以官方最新文档为准。

文章标签

微信小程序登录态token安全

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。

微信小程序订阅消息用户召回

小程序订阅消息与用户召回:模板消息退场后的合规触达

订阅消息的本质是把触达选择权还给用户:一次授权一条消息,营销式群发走不通。正确做法是在下单、预约等关键节点顺势请求授权,服务端管理订阅额度,用服务通知加短信、会员权益做合规召回组合。

小程序约 6 分钟阅读