微信小程序的登录这块我在 uni-app 项目里前前后后改过七八个版本从最早一上来就调 getUserInfo 弹框到后来被审核打回、被真机上的各种诡异现象折磨再到现在基本收敛成一套自己用着顺手的写法。很多人第一次写 uni-app 微信小程序授权登录的时候最容易犯的错不是代码写错而是根本没想清楚登录这件事在小程序里到底分几层哪一层是微信给你的身份哪一层是你自己业务系统的身份这两者之间的桥梁又是谁。代码抄过来能跑但一旦遇到 session 过期、多端打通、或者用户第二次进来发现又要重新授权就完全不知道从哪下手了。这篇就把 uni-app 环境下微信小程序授权登录的完整链路拆开讲包括前端怎么拿 code、后端怎么换 openid、业务 token 怎么签发和维护、头像昵称和手机号这些进阶授权能力现在还能不能用、以及真机和开发者工具上那些让人抓狂的差异。代码部分我会尽量把每一行的意图都注释清楚但比代码更重要的是每一步为什么这么设计——这部分文档里基本不会写全是踩出来的。1. 先搞清楚微信登录体系里的三个身份别把它们混成一锅粥在写第一行代码之前我建议先把三个概念分清楚否则后面所有的 bug 都源于这里。这三个身份分别是 openid、unionid 和业务 token它们分别属于不同的系统生命周期也完全不同。1.1 openid 是这个用户在这一款小程序里的唯一编号openid 是微信给用户分配的、针对某一个具体小程序的唯一标识。同一个用户在 A 小程序里的 openid 和在 B 小程序里的 openid 是两个完全不同的字符串互相之间没有任何关联。这一点非常关键因为很多人在做多端的时候会想当然地认为同一个微信号 openid 应该一样吧结果发现对不上白白浪费半天时间。openid 的获取路径只有一条小程序前端通过uni.login拿到临时的code把这个 code 传给自己的后端后端再拿着appid secret code去请求微信的服务端接口换回openid和session_key。整个过程 openid 绝对不会在小程序前端出现这一点也要记住前端拿不到也没必要拿到。1.2 unionid 才是打通多端的钥匙但它有前提条件如果你的产品同时有小程序、公众号、App 甚至网站你想知道这个在小程序里下单的人是不是就是公众号里的那个粉丝靠 openid 是做不到的必须用 unionid。unionid 是同一个用户在同一个微信开放平台账号下的唯一标识跨应用保持一致。但 unionid 不是白给的它有硬性前提这些小应用必须绑定在同一个微信开放平台账号下。绑定之后jscode2session接口的返回里才会带上 unionid 字段如果没绑定这个字段压根不会出现。我见过不少人写代码的时候直接res.data.unionid拿去当用户主键本地测试环境因为账号绑过所以有值换了个新项目、没绑开放平台就全变成 undefined 了数据库里一堆 null 主键。所以正确做法是先判空有就用 unionid 做跨端关联没有就老实退回用 openid。1.3 业务 token 是你自己签发的登录态session_key 绝对不能当登录态用这是我最想强调的一点。很多人第一次做小程序登录看到后端返回了session_key觉得这东西既然是微信给的、又能用来解密手机号那就直接把它当登录凭证存到前端 localStorage 里吧。这是非常危险的做法原因有三个。第一session_key是微信用来做数据加解密的密钥它的作用是解密encryptedData不是用来做身份校验的。第二session_key会过期而且微信不会主动通知你它什么时候过期你只能通过uni.checkSession去问或者等解密失败的时候才知道。第三一旦session_key泄露别人理论上可以伪造解密流程风险等级完全不是普通 token 能比的。正确的做法是session_key只存在于你的后端最好放在 Redis 或者服务端 session 里用 openid 作为 key比如wx:session:openid_xxx。然后你自己签发一个业务 token 返回给前端前端只认这个 token。这个 token 的生成规则、过期时间、刷新策略完全由你自己控制跟微信没关系。这样即使将来你要换登录方式前端的逻辑也不用大改。2. 登录按钮之前manifest 配置和那些一上线就被打回的细节代码写得再漂亮配置没弄对一样跑不起来。这部分内容看着琐碎但每一条都是真实项目里会卡住你的地方。2.1 manifest.json 里 mp-weixin 节点要改哪几项在 uni-app 项目里微信小程序的配置集中在manifest.json的mp-weixin节点下。最核心的是appid这个必须是你在微信公众平台申请到的小程序 AppID不能填测试号测试号的 openid 会变而且很多接口调不了。另外setting里有一项urlCheck开发者工具里的表现对应的是不校验合法域名、web-view 业务域名、TLS 版本以及 HTTPS 证书。{ mp-weixin: { appid: wx1234567890abcdef, setting: { urlCheck: false, es6: true, minified: true, postcss: true }, usingComponents: true, optimization: { subPackages: true } } }这里要特别注意urlCheck: false只在开发阶段方便你连本地或者测试服务器用正式发布前一定要在微信公众平台的开发管理 - 开发设置 - 服务器域名里把 request 合法域名配好而且必须是 HTTPS、必须备案。很多人本地调通了一上真机就请求失败99% 就是这个问题。2.2 隐私协议与授权弹窗现在不做这一步登录接口直接不给用从 2023 年开始微信对小程序的隐私合规抓得很严。如果你的小程序用到了用户信息相关的接口包括登录、手机号、位置等必须在manifest.json或者公众平台后台配置《小程序用户隐私保护指引》并且在代码里处理wx.requirePrivacyAuthorize或者配置__usePrivacyCheck__。在 uni-app 里的做法是在manifest.json的mp-weixin节点加{ mp-weixin: { __usePrivacyCheck__: true } }加上这个之后微信会在你调用隐私接口的时候自动弹出隐私协议弹窗。如果没配用户点了登录按钮之后可能什么反应都没有控制台也不报明显错误只有一句关于隐私的提示很容易被忽略。我遇到过最坑的一次是开发工具上一切正常真机上点击登录完全无响应查了两个小时才发现是隐私协议没配。2.3 登录按钮的写法以及必须用户主动触发这条红线微信有一条规则所有获取用户信息的授权弹窗必须由用户的点击行为触发不能在小程序启动的时候自动弹。所以你的登录流程一般是这样的小程序启动时先做一次静默登录只调uni.login拿 code不弹任何框如果后端返回的 token 还有效就直接进首页token 无效或者需要用户信息的时候才在页面上放一个按钮等用户点了再走完整的授权流程。template view classlogin-wrap !-- 授权登录按钮必须是用户点击触发 -- button classlogin-btn clickhandleLogin微信登录/button /view /template按钮本身不需要open-typegetUserInfo了那个属性早就失效了。就是一个普通的点击事件里面自己调uni.login拿 code然后发给后端。这个细节很多人还在抄几年前的博客结果发现点了没反应。3. 核心链路从 uni.login 拿 code 到后端 code2session 换 openid这是整篇文章最关键的一段我把前后端的完整实现都写出来注释尽量写清楚每一行的目的。3.1 前端封装一个可复用的 login 方法先看前端部分。uni.login在小程序端和 App 端的行为不太一样小程序端直接返回codeApp 端会走微信 SDK 的授权流程。我们这里只关注微信小程序。/** * 获取微信登录 code * 注意code 有效期 5 分钟且只能使用一次 * 调用一次就必须立刻发给后端不能缓存复用到第二次 */ function getWxCode() { return new Promise((resolve, reject) { uni.login({ provider: weixin, success: (res) { // res.code 就是我们要的临时凭证 if (res.code) { resolve(res.code) } else { reject(new Error(未获取到 code可能是用户取消或环境异常)) } }, fail: (err) { // 常见的 fail 原因基础库版本过低、非微信环境调用 reject(err) } }) }) } /** * 完整的授权登录流程 */ async function doLogin() { try { // 第一步拿 code const code await getWxCode() // 第二步把 code 发给自己的后端 // 这里不要用 uni.request 之外的第三方请求库避免拦截器冲突 const res await uni.request({ url: https://your-domain.com/api/auth/wx-login, method: POST, data: { code } }) // 第三步拿到业务 token 并存起来 const { token, expiresIn } res.data uni.setStorageSync(token, token) // 记录过期时间戳方便后续做主动刷新 uni.setStorageSync(token_expire_at, Date.now() expiresIn * 1000) return token } catch (e) { // 这里是关键不要静默失败要给出可读的错误提示 console.error([login failed], e) uni.showToast({ title: 登录失败请重试, icon: none }) throw e } } export { getWxCode, doLogin }这段代码有两个容易踩的点。第一code是一次性的如果你在success回调里先把 code 存下来、等用户点了同意隐私协议之后再用那大概率会拿到 40163 错误code 已被使用。所以拿到 code 之后要立刻请求后端。第二uni.request的fail分支和success分支里 HTTP 状态码非 200 的情况要分开处理前者是网络层问题后者是业务层问题混在一起排查会非常痛苦。3.2 后端 code2session 的处理与 token 签发后端这部分我用 Node.js 举例逻辑换到 Java、Python、PHP 都是一样的。核心就是拿appid secret code去请求微信的接口。const axios require(axios) /** * 微信登录主流程 * param {string} code 前端传来的临时凭证 */ async function wxLogin(code) { const { WX_APPID, WX_SECRET } process.env // 第一步用 code 换 openid 和 session_key const url https://api.weixin.qq.com/sns/jscode2session const { data } await axios.get(url, { params: { appid: WX_APPID, secret: WX_SECRET, js_code: code, grant_type: authorization_code // 固定值 }, timeout: 5000 // 一定要设超时微信接口偶尔会慢 }) // 微信的错误是通过 errcode 返回的HTTP 状态码依然是 200 if (data.errcode) { throw new Error(wx error ${data.errcode}: ${data.errmsg}) } const { openid, session_key, unionid } data // 第二步session_key 只存服务端绝不返回给前端 // 建议用 Rediskey 用 openid设置 30 分钟过期 await redis.set(wx:session:${openid}, session_key, EX, 1800) // 第三步查库或者建号。优先用 unionid没有就退回 openid const primaryKey unionid || openid let user await db.user.findOne({ wxKey: primaryKey }) if (!user) { user await db.user.create({ wxKey: primaryKey, openid, unionid: unionid || , nickname: 微信用户, createdAt: new Date() }) } // 第四步签发自己的业务 token const token jwt.sign( { uid: user.id, openid }, process.env.JWT_SECRET, { expiresIn: 7d } ) return { token, expiresIn: 7 * 24 * 3600, userInfo: { id: user.id, nickname: user.nickname, avatar: user.avatar } } }这段代码里有几个设计决策值得展开说。第一处是超时设置微信的jscode2session接口虽然绝大部分时候很快但偶尔会有几百毫秒到一两秒的抖动如果不设超时你的接口会被拖着一起慢用户体验很差。第二处是session_key的存储位置用 Redis 而不是数据库因为它是高频读写的临时数据而且必须支持自动过期。第三处是 unionid 的兜底逻辑这个在前面已经强调过了。还有一个细节jscode2session这个接口有频率限制虽然官方文档里没有明确写死一个很小的数字但同一个 openid 频繁调用是会被风控的。所以千万不要在前端做每次页面跳转都重新登录一次这种事登录态应该是长久的只在需要的时候刷新。3.3 静默登录和主动授权登录该怎么组合这两个概念经常被混着说其实是两件事。静默登录指的是不弹任何授权框直接调uni.login拿 code 换 openid用户完全无感。它的作用是在用户第一次打开小程序的时候就把这个人的匿名身份建立起来这样他浏览商品、加购物车这些操作都能关联到同一个账号上。主动授权登录指的是获取用户的头像、昵称、手机号这些敏感信息必须用户点击确认。它的作用是把一个匿名身份变成一个可联系、可运营的实名身份。我一般采用的策略是小程序onLaunch时先尝试静默登录如果本地有 token 且未过期直接用如果没有或者过期了走一次静默登录拿新 token同时把用户标记为未完善资料。然后在需要用户信息的页面比如下单页、个人中心再放一个按钮引导用户授权头像昵称。这样用户第一次进来不会被打扰体验流畅得多。4. 头像、昵称和手机号能力变了之后应该怎么接这部分是坑最多的地方因为微信这几年陆续收紧了几个关键接口网上大量老教程已经完全不适用了。4.1 getUserProfile 的现状与替代方案wx.getUserProfile在 2022 年 10 月 25 日之后被调整新版本返回的头像和昵称都是匿名的灰色头像、微信用户。也就是说这个接口现在只能拿到一个占位信息拿来初始化展示可以但拿来当真实用户资料没意义了。很多 uni-app 项目还在用uni.getUserProfile代码能跑通不报错但拿到的数据是假的测试的时候不看日志根本发现不了。我的建议是直接放弃这个接口改用下面要说的头像昵称填写能力。4.2 头像昵称填写能力chooseAvatar 和 nickname 类型输入框微信官方给的替代方案是两个组件能力button的open-typechooseAvatar用来选头像input的typenickname用来填昵称。template view classprofile-form !-- 头像选择用户从微信头像或相册里选一张 -- button classavatar-btn open-typechooseAvatar chooseavataronChooseAvatar image :srcavatarUrl || defaultAvatar classavatar / /button !-- 昵称输入typenickname 会带出微信昵称建议 -- input typenickname classnickname-input placeholder请输入昵称 :valuenickname bluronNicknameBlur / /view /template script export default { data() { return { avatarUrl: , nickname: } }, methods: { // 拿到的是本地临时文件路径必须上传到自己的服务器 onChooseAvatar(e) { const { avatarUrl } e.detail this.avatarUrl avatarUrl // 这里调用 uni.uploadFile 把临时文件传到自己的 OSS this.uploadAvatar(avatarUrl) }, onNicknameBlur(e) { this.nickname e.detail.value } } } /script这里有个非常容易忽略的坑chooseAvatar返回的avatarUrl是一个本地临时路径形如http://tmp/xxx或者wxfile://xxx它只在本次会话有效小程序重启之后就失效了。所以拿到之后必须马上uni.uploadFile传到自己的服务器或者云存储然后把返回的永久 URL 存到数据库。我见过有人直接把临时路径存进了数据库结果第二天用户头像全变成裂图。另外昵称输入框用typenickname的时候微信会在输入框聚焦时给出用户微信昵称的快捷填充建议用户点击一下就能填入。这个体验比让用户手动打字好太多也规避了合规风险。4.3 getPhoneNumber 的两种模式与后端解密手机号是获取成本最高的一个信息因为它直接关系到商业价值。目前有两个版本的能力。旧版是通过button open-typegetPhoneNumber在回调里拿到encryptedData和iv然后后端用session_key做 AES-128-CBC 解密。这个方案的问题是依赖session_key而session_key会过期用户如果放了很久才点按钮解密就会失败。新版基础库 2.21.2 及以上改成在回调里拿到一个code后端拿这个 code 去请求微信接口换取手机号完全不依赖session_key稳定性好得多。// 前端 onGetPhoneNumber(e) { // 新版返回的是 code旧版是 encryptedData iv const { code, errMsg } e.detail if (!code) { // 用户拒绝了授权 return } uni.request({ url: https://your-domain.com/api/auth/bind-phone, method: POST, data: { code }, success: (res) { this.phone res.data.phoneNumber } }) }// 后端用 access_token code 换取手机号 async function getPhoneNumber(code) { // access_token 需要缓存不能每次都重新获取 const accessToken await getAccessToken() const { data } await axios.post( https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token${accessToken}, { code } ) if (data.errcode ! 0) { throw new Error(get phone failed: ${data.errmsg}) } return data.phone_info.purePhoneNumber }这里最需要注意的是access_token的缓存。微信的access_token有效期是 7200 秒而且每天有获取次数上限2000 次左右如果每次请求都去重新获取很快就会把额度用光导致线上所有接口都挂掉。正确做法是在 Redis 里缓存提前 5 到 10 分钟刷新并且加一把分布式锁防止并发重复获取。5. 登录态维护token 存储、请求拦截与过期续期的完整方案登录成功只是开始真正让项目稳定的是登录态的管理。5.1 token 存哪里、存多久过期策略怎么定在 uni-app 里常用的存储方式是uni.setStorageSync它对应小程序端的wx.setStorageSync数据存在本地除非用户主动删除小程序否则一直在。所以 token 存这里没问题但要同时存一个过期时间戳。我的习惯是token本身有效期设 7 天同时在本地存token_expire_at。每次发请求之前先看一下还剩多久如果剩余时间小于 1 小时就触发一次静默刷新把 token 续上。这样只要用户还在使用就基本不会遇到突然要重新登录的情况。用双 token 的方案会更严谨一些accessToken短比如 2 小时refreshToken长比如 30 天。接口用 accessToken 鉴权过期了就用 refreshToken 换新的。这个方案在 App 端更有必要小程序端因为打开频率高单 token 加自动刷新其实够用了。5.2 用 uni.addInterceptor 做统一的请求拦截uni-app 提供了uni.addInterceptor来拦截特定 API 的调用最常用的就是拦截request。// 请求队列用于处理 token 过期时的并发请求 let isRefreshing false let pendingRequests [] function addRequestInterceptor() { uni.addInterceptor(request, { invoke(args) { // 每次请求自动带上 token const token uni.getStorageSync(token) if (token) { args.header { ...args.header, Authorization: Bearer ${token} } } return args }, fail(err) { console.error([request fail], err) } }) }这里有个坑uni.addInterceptor是全局生效的如果你在项目里混用了 axios 或者其他请求库它们的请求不会走这个拦截器导致有些请求漏带 token。所以要么统一用uni.request要么统一用 axios别混着来。还有一个更隐蔽的问题拦截器是在 uni-app 框架层做的某些插件比如 uni-simple-router 或者一些 UI 库内部封装的请求可能会绕过它。排查请求不带 token 的问题时先确认这个请求到底有没有走uni.request。5.3 401 之后的重新登录与并发请求去重这是登录态管理里最有技术含量的一段。当 token 过期后端返回 401前端需要自动重新登录。但问题是一个页面上可能同时发出去五六个请求它们几乎同时收到 401如果每个都触发一次登录就会产生五次uni.login而 code 是一次性的后四次必定失败。解决办法是用一个刷新锁加一个等待队列。async function handle401(config) { if (isRefreshing) { // 已经有请求在刷新了把当前请求挂起等待 return new Promise((resolve) { pendingRequests.push(() resolve(retry(config))) }) } isRefreshing true try { const newToken await doLogin() // 重新静默登录 // 刷新完成把挂起的请求全部重放 pendingRequests.forEach((cb) cb()) pendingRequests [] return retry(config) } finally { isRefreshing false } }这段逻辑看着简单但真正写好需要处理异常情况如果重新登录也失败了怎么办我的做法是把挂起的请求统一 reject并且跳转到登录页同时给用户一个明确的提示。千万不要让请求永远挂在那里那会导致页面一直 loading用户以为卡死了。6. 真机、开发者工具与线上环境的差异排查同一个登录流程在开发者工具里跑得好好的一上真机就报错这种情况太常见了。下面是我整理的一份排查对照表。6.1 常见错误码和对应原因错误码含义常见原因处理方式40029invalid codecode 被重复使用或已过期确保拿到 code 立刻使用不缓存40163code been used同一 code 请求了两次检查是不是有重试逻辑重复调用40013invalid appidappid 填错或与 secret 不匹配核对 manifest 和后端配置40125invalid appsecretsecret 填错重新在公众平台生成45011频率限制短时间内请求过多加缓存避免重复登录-1系统繁忙微信侧抖动加退避重试不要立刻放弃这张表建议贴在项目文档里遇到问题先对一遍能省下大量时间。6.2 真机请求打不到后端的几种典型原因第一种也是最常见的公众号后台没有配置 request 合法域名。开发者工具里勾了不校验合法域名所以能跑真机预览和正式版都不认这个设置必须配置。域名必须是 HTTPS并且已经完成备案。第二种HTTPS 证书链不完整。有些服务器只配了站点证书没配中间证书浏览器和开发者工具会自动补全但小程序的网络库不会结果是握手失败。用在线工具检测一下证书链完整性就能确认。第三种真机调试模式下和预览模式下网络环境不同。真机调试是通过开发者工具转发请求的走的是电脑的网络预览模式是手机自己的网络。如果你用局域网 IP 做接口地址真机调试能通预览就通不了。这种情况老老实实换成公网可访问的测试域名就好。6.3 开发者工具里 network: unavailable 到底是怎么回事这个现象我在 uni-app 项目里遇到过好几次。微信开发者工具的 Network 面板里某个请求显示network: unavailable看起来像是失败了但后端日志显示请求已经到达并且正常返回了。原因是 uni-app 编译到小程序之后请求链路会经过框架的适配层某些版本的开发者工具在解析这个链路的调用栈时会丢失信息于是显示 unavailable。它不代表请求失败。判断请求到底成没成功最靠谱的方式是看后端日志或者在真机调试模式下打开 vConsole 看实际返回。所以遇到这个提示先别急着改代码先去后端确认请求有没有到。如果到了那就是工具的显示问题忽略即可。7. 我在实际项目里踩过的几个坑和最终收敛的写法前面讲的都是相对体系化的东西最后说几个零碎的、但特别容易翻车的点。第一个是关于uni.login的调用时机。有些同学喜欢在App.vue的onLaunch里直接调uni.login这在大部分情况下没问题但如果你同时用了分包或者某些插件在启动阶段做了重定向可能会因为环境还没准备好而失败。我的做法是在onLaunch里加一个极短的延迟比如setTimeout100 毫秒或者干脆放到首页的onLoad里让它晚一点点执行稳定性会好一些。第二个是关于本地存储的读取时机。uni.getStorageSync是同步 API理论上随取随用但在小程序冷启动的极早期比如onLaunch的第一行某些机型上可能会返回空。这个概率很低但一旦遇到就是偶现的登录失效排查起来极其痛苦。我的做法是在App.vue里用一个Promise包一层等onLaunch完成后再去读存储避免这种玄学问题。第三个是关于多端兼容。如果你的 uni-app 项目同时要发小程序和 Appuni.login在两个平台的行为是不一样的。App 端的微信登录需要在manifest.json里配置微信 AppID 和 Universal Links而且拿到的不是 code 而是直接的用户信息后端处理逻辑完全不同。所以我的建议是在项目早期就把登录逻辑抽象成一层接口比如authService.login()小程序和 App 各写一个实现上层业务代码只调接口这样加平台的时候不用改业务代码。第四个是关于测试。登录这块一定要准备一个账号状态重置的调试入口能一键清掉本地 token、清掉后端 Redis 里的 session、清掉开发者工具的缓存。光靠手动删小程序重进效率太低了。我在项目里加了一个隐藏的调试页面连点 logo 五次才能打开里面就三个按钮清本地、清服务端、模拟 token 过期。这个小东西至少帮我节省了几十个小时的排查时间。最后再提一句关于注释的事。这篇标题里写了带注释但我想说的是注释的重点不是解释这行代码在做什么而是记录为什么这么写。比如// session_key 只存服务端这句话半年后接手你代码的人看到就知道这里不能随便改而// 赋值给变量这种注释纯粹是噪音。我一般会在三个地方写注释涉及微信接口的特殊参数、涉及安全边界的处理、以及那些看起来多余但实际是为了绕开某个已知问题的代码。第三类最重要因为如果不写清楚原因后人优化代码的时候很可能就把你的防御性写法给删掉了然后 bug 又回来了。