微信小程序登录开发，一文讲透认证流程与常见坑

微信小程序的登录，可能是每个小程序开发者绕不开的第一道坎。你以为不就是调个`wx.login`拿个code，再换openid吗？真到自己动手，各种“坑”能让你从下午三点调试到凌晨。我见过太多人，包括我自己，第一次做的时候，被那套`code2Session`的流程搞得怀疑人生。今天这篇文章，就专门把这块掰开揉碎了讲清楚，从最基础的认证流程，到那些文档里不会明说、但实战中必踩的坑，一次性给你说透。

先说最核心的认证流程，它其实就三步，但每一步都藏着细节。第一步，前端调用`wx.login()`，这个接口会默默地帮你生成一个临时的登录凭证，我们叫它`code`。注意，这个`code`有效期只有五分钟，而且只能用一次，用完了就作废。第二步，前端得把这个`code`通过你自己的服务器接口传给后端。记住，是传给你自己的后端，不是直接传给微信服务器。第三步，你的后端拿着这个`code`，加上小程序的`AppID`和`AppSecret`，去请求微信的接口`https://api.weixin.sns/jscode2session`。微信那边校验通过后，会返回给你一个`openid`和`session_key`。`openid`就是用户在这个小程序里的唯一身份证，`session_key`则是用来解密用户敏感信息的密钥。

这个流程听起来简单吧？但坑就坑在，很多新手会把`code`当成一个可以反复使用的令牌，或者干脆直接把`AppSecret`塞进前端代码里。我再说一遍，`AppSecret`是你的后端和微信服务器之间的“保险柜钥匙”，一旦暴露在客户端，别人就能冒充你的小程序，获取任意用户的`openid`，这属于严重的安全事故。所以，`code2Session`这个请求，必须、必须、必须发生在你的后端，前端永远不要碰`AppSecret`。这是一个底线，踩了就是事故。

流程走通了，接下来就是最经典的坑：`session_key`到底怎么用？很多文章告诉你，拿到`session_key`之后要存起来，方便以后解密手机号或者获取用户信息。但实际情况是，微信为了安全，每次`wx.login`生成的`code`换来的`session_key`都可能不一样，而且它不会主动告诉你旧的失效了。如果你在前端每次登录都调`wx.login`，而后端又拿旧的`session_key`去解密，那你大概率会碰到`decryptData`解密失败，报错`-41003`。这个错我当年排了一下午，发现是前端在页面`onShow`里反复调了`wx.login`，导致后端存的`session_key`被覆盖了。

那正确的做法是什么？核心思路是，不能让前端频繁地触发`wx.login`。你的小程序应该有一套自己的登录态维护机制。我建议的做法是：前端先调`wx.login`拿到`code`，发给后端换`openid`和`session_key`。后端拿到这两个值后，自己生成一个自定义的登录态，比如一个随机字符串`token`，然后把这个`token`和`openid`、`session_key`关联起来存到数据库或缓存里。后端把`token`返回给前端，前端存在`storage`里。之后所有需要登录态的请求，前端只带这个`token`，后端根据`token`去查对应的用户信息，而不是每次都去调微信接口。只有当后端检测到`token`过期，或者用户主动退出时，前端才需要调用`wx.login`。

这个设计能避开第二个大坑：`wx.login`的调用时机混乱。我看到过有些代码，在`app.js`的`onLaunch`里调一次，在首页的`onLoad`里又调一次，结果两个`code`先后发到后端，后一个覆盖了前一个，导致第一个请求的会话失效。你想想，如果用户刚进入页面就发了一个请求，这个请求带着旧`token`，而后端因为`session_key`被覆盖，解密失败，这体验能好吗？所以，登录逻辑一定要收敛，最好封装成一个独立的模块，统一管理状态，谁需要登录，就调用这个模块的方法，而不是到处散落着`wx.login`的调用。

再来说说第三个坑，关于`openid`和`unionid`的区别。`openid`是每个小程序内唯一的，同一个用户，在你不同的小程序里，`openid`是不同的。如果你有多个小程序，或者还有公众号、App，想识别同一个用户，那就需要`unionid`。但注意，`unionid`不是随便就能拿到的，它要求你的多个应用必须绑定在同一个微信开放平台账号下。如果你没绑定，你调`code2Session`拿到的就只有`openid`，没有`unionid`。很多新手不知道这个，以为`openid`就能通用，结果做用户打通时发现数据对不上，一脸懵。

还有一个容易被忽略的细节，是`code`换`session_key`的接口有频率限制。虽然微信官方文档没写死具体数字，但如果你在短时间内用同一个`AppSecret`疯狂调用，是会被临时封禁的。我见过一个测试环境，因为自动化脚本写得不严谨，循环调用登录接口，直接把那个小程序的`AppSecret`给封了两个小时。所以，写测试代码的时候，也别忘了给登录接口加个节流或者缓存，别让测试脚本变成攻击脚本。

解决了这些，再聊聊关于用户信息的获取。现在的微信规范是，`wx.getUserInfo`这个接口，如果你不是在小程序后台配置了“用户隐私保护指引”，并且用户主动点击按钮触发，你是拿不到昵称和头像的，返回的都是默认的灰色头像和“微信用户”。所以，现在的登录流程，早就不是“登录即拿头像昵称”了。你需要引导用户去点击一个“授权”按钮，通过``和``来收集信息。这个改动让很多老项目直接报错，因为以前只要登录成功就能拿到`userInfo`，现在必须得用户主动操作。

关于登录态的过期时间，这也是个容易想当然的坑。微信的`session_key`有效期是不固定的，官方说“可能会变化”，但实际上它和用户的使用频率有关，长期不用会失效，但频繁使用也可能就一直在。你后端自己生成的`token`，如果设置过期时间太短，比如30分钟，用户玩着玩着突然弹个“登录已过期”，体验很糟糕；如果设置太长，比如30天，又可能带来安全风险。我的建议是，`token`的有效期设成72小时，同时做一个“静默续期”机制，就是当后端在请求里发现`token`快过期了，就在响应头里带一个新的`token`，前端收到后自动替换。这样用户无感知，安全性和体验都能兼顾。

说到这，基本上把微信小程序登录的流程和最常见的几个坑都覆盖了。其实回过头看，这些坑的根源大多是对微信那套“临时凭证+后端换身份”的机制理解不够透彻。记住核心逻辑：前端拿的是“临时小车票”，后端拿“小车票”去换“长期通行证”。只要这个思想不歪，遇到问题多去查`code2Session`的返回码，多想想是不是`session_key`被覆盖了，是不是`AppSecret`泄露了，你就能少走很多弯路。下一次再碰到登录问题，别慌，按着这个思路排查，大概率能快速定位。毕竟，登录是门面，门面稳了，里面才好干活。

原文来自：小程序开发

下一篇：App跳转微信小程序全攻略，几步轻松搞定 上一篇：企业微信小程序定制开发，助力公司数字化转型提速