微信小程序登录模块与个人信息获取合规实战指南

做小程序开发，绕不开的第一道坎就是登录模块。不管是电商、社区团购、生鲜配送还是工具类小程序，只要涉及用户身份，登录就是地基。而个人信息这块，既是功能需求，又是合规红线。微信这边对于登录能力、头像昵称获取方式、手机号解密规则的调整也特别频繁，我去年就因为在登录模块上踩了老版本的接口坑，被用户投诉了两次。

这篇内容我把“微信小程序登录模块与个人信息”从头到尾梳理一遍，基于我实际开发中落地的方案来讲。适合正在做小程序、被登录态和用户资料获取搞到头大的开发者。我会讲清楚登录链路的来龙去脉、代码怎么写、后端怎么校验、个人信息怎么合规获取和存储，以及我遇到过的奇葩问题。不要照抄老教程，里面很多API已经变了。

1. 登录模块的整体设计思路

1.1 微信登录不是一套接口，是三段协作的链路

很多刚接触小程序的开发者容易把登录理解成“前端调用wx.login然后拿到openid就完事”。这是最典型的误区。微信小程序的登录，本质上是前端、微信服务器、你的后端服务器三方协同完成的一次身份认证过程。

前端通过wx.login()拿到一个临时登录凭证code，这个code的有效期只有5分钟，而且只能使用一次。前端把这个code传给自己的后端，后端再拿着code去请求微信的接口，换取openid、session_key等信息。这里的openid是用户在某个小程序下的唯一标识，换了小程序openid就变了，同一个人的不同小程序之间无法直接用openid打通。session_key则是用于解密敏感数据（比如手机号）的密钥。

整个链路可以拆成四步：

1. 前端调用wx.login()拿到code。
2. 前端通过自己后端接口把code传过去。
3. 后端用code向微信服务器发起请求，换取openid和session_key。
4. 后端把openid等数据与用户表关联，自己生成登录态（比如token），并返回给前端存储。

这个过程中，你的后端是唯一能和微信服务器直接交换code的节点。前端绝对不应该自己去请求微信的code换session接口，否则你的appid和secret就可能暴露在客户端代码里。这是登录模块设计的第一条安全准则。

1.2 为什么必须由后端换openid，而不是让微信直接返回给前端

这个问题我和很多人解释过。微信提供了接口可以根据code获取openid，但前提是你得在请求中带上appid和secret。appid本身就在你的小程序代码里，暴露问题不大，但secret是绝对不能出现在客户端的，它是你作为小程序开发者的身份凭证。如果把secret放在前端，别人反编译代码就能拿到，然后伪造成你的小程序调用微信接口，带来的后果可能是数据泄露、接口被刷、甚至资产损失。

所以标准做法是：前端永远只拿code，后端负责拿着code找微信换数据。后端还可以把这个过程做得更细一些，比如拿到openid之后先去数据库查用户是否存在，不存在就在同一事务里自动注册，存在就正常登录。这样用户第一次进入小程序的时候，后台已经悄悄把账号做好了，用户完全无感。

还需要注意一点：openid不能直接作为业务登录态的凭证返回给前端。因为openid是固定的，一旦泄露，别人拿着你的openid就能冒充你。正确做法是后端自己生成一个随机token（比如UUID或者JWT），把这个token和openid、用户ID绑定存在服务端，前端每次请求都带这个token，后端通过token确定用户身份。token还可以设置过期时间，比openid安全得多。

2. 登录模块从零到一：前端请求封装与后端鉴权实现

2.1 前端请求封装，别让你每个登录调用都写成一把梭

项目做多了你会发现，如果每个页面都直接调wx.request，后续拓展登录态、统一处理错误、加loading都会很痛苦。所以我建议一开始就把request封装成一个公共模块，登录流程只是这个封装里的一个典型应用场景。

我之前在一个社区团购项目里就是这么干的。封装的核心逻辑是：统一拼接baseURL、统一在请求头里携带token、统一处理HTTP状态码、统一处理业务code（比如登录过期）、统一处理网络异常。这样登录接口、用户信息接口、商品列表接口都共用一套逻辑，后面排查问题的时候能省不少事。

这是一段简化版的请求封装示例，实际使用可以继续完善：

// utils/request.js const baseURL = 'https://api.example.com' function request(url, method = 'GET', data = {}, needAuth = true) { return new Promise((resolve, reject) => { const token = wx.getStorageSync('token') const header = { 'Content-Type': 'application/json' } if (needAuth && token) { header['Authorization'] = `Bearer ${token}` } wx.request({ url: baseURL + url, method, data, header, success(res) { // 假设后端返回结构为 { code, data, msg } if (res.data.code === 0) { resolve(res.data.data) } else if (res.data.code === 401) { // 登录态过期，清掉本地token，跳转登录页 wx.removeStorageSync('token') wx.navigateTo({ url: '/pages/login/login' }) reject(new Error('登录已过期')) } else { wx.showToast({ title: res.data.msg || '请求失败', icon: 'none' }) reject(new Error(res.data.msg)) } }, fail(err) { wx.showToast({ title: '网络异常', icon: 'none' }) reject(err) } }) }) } module.exports = { request }

登录的时候，前端就是调用wx.login拿code，然后通过这个request请求后端接口：

// pages/login/login.js const { request } = require('../../utils/request') async function wxLogin() { return new Promise((resolve, reject) => { wx.login({ success: res => resolve(res.code), fail: err => reject(err) }) }) } async function handleLogin() { try { const code = await wxLogin() const data = await request('/auth/login', 'POST', { code }, false) // 登录成功后后端会返回token以及用户信息 wx.setStorageSync('token', data.token) wx.setStorageSync('userInfo', data.userInfo) // 跳回上一页或首页 wx.navigateBack() } catch (err) { console.error('登录失败', err) } }

2.2 后端登录接口设计：code换session只是第一步

后端接口设计我建议做成一个独立的auth模块。接口接收前端传过来的code，然后调用微信的jscode2session接口。这个接口的请求地址是https://api.weixin.qq.com/sns/jscode2session，需要传appid、secret、js_code以及grant_type=authorization_code。

实际返回的数据大致长这样：

{ "openid": "oK3X5uI...", "session_key": "tJ1lM0...", "unionid": "oU7c0..." }

如果用户没有绑定过开放平台账号，是不会有unionid的。拿到openid之后，后端去数据库查用户表，不存在就创建一条新用户记录。这里要注意，用户表里除了主键id、openid之外，一般还要存nickname、avatar、phone、status等字段。首次自动注册时，这些字段默认是空的，等用户主动填写或者授权后再补充。

然后后端生成自己的登录态。我通常使用jwt，把userId和openid放进payload，设置有效期7天。用jwt的好处是服务端不需要维护session状态，每次请求解析token即可。但要注意把secret配置在服务端环境变量里，不要写在代码仓库中。

后端伪代码（以Node.js为例）：

const axios = require('axios'); const jwt = require('jsonwebtoken'); router.post('/auth/login', async (req, res) => { const { code } = req.body; if (!code) return res.status(400).json({ code: 1, msg: '缺少code' }); const result = await axios.get('https://api.weixin.qq.com/sns/jscode2session', { params: { appid: process.env.WX_APPID, secret: process.env.WX_SECRET, js_code: code, grant_type: 'authorization_code' } }); const { openid, session_key } = result.data; if (!openid) return res.status(500).json({ code: 1, msg: '微信登录失败' }); let user = await User.findOne({ where: { openid } }); if (!user) { user = await User.create({ openid, nickname: '', avatar: '', phone: '' }); } const token = jwt.sign({ userId: user.id, openid }, process.env.JWT_SECRET, { expiresIn: '7d' }); res.json({ code: 0, data: { token, userInfo: { id: user.id, nickname: user.nickname, avatar: user.avatar, phone: user.phone ? user.phone.replace(/^(\d{3})\d{4}(\d{4})$/, '$1****$2') : '' } } }); });

这里返回userInfo时我就顺手做了手机号脱敏，后面会详细聊。登录接口的另一个关键点是：同一个code不能重复使用，如果你调试时报错说code无效，先看看这个code是不是已经被用过了。

2.3 登录态的维护与刷新策略

登录态不是一次登录就永久有效的。token有效期到了，或者用户在小程序里被手动清掉缓存，都会导致登录态失效。我的做法是在请求封装里统一处理401，自动跳到登录页触发重新登录。但如果每次token过期都让用户手动点一次登录，体验太差了。

更好的策略是静默刷新。具体做法是：后端在返回token时，同时返回一个refresh_token，并且refresh_token的有效期更长（比如30天）。当请求发现access_token过期时，前端用refresh_token去换新的access_token。这个思路在Web端很常见，小程序里也适用。

不过大部分业务小程序其实不需要做这么重。我实际用到最多的方案是：只要token过期，就用wx.login重新走一遍登录流程。因为小程序登录本来就是无感的，wx.login不会让用户输入账号密码，也不需要弹窗授权，所以静默刷新可以简单不少。用户在操作过程中如果某次请求发现401，前端自动重新登录然后重放刚才的请求。

需要注意一个细节：wx.login拿code，用户不需要主动触发，只要在小程序环境里就能调用。所以自动刷新登录态在用户看来是完全无感的。

3. 个人信息的获取与展示：从授权弹窗到组件填写

3.1 别再写getUserInfo拉取头像昵称了，现在已经走不通

如果你翻开两三年前的小程序教程，里面很多还在教用wx.getUserInfo或者button的open-type="getUserInfo"去弹窗获取用户头像昵称。这是个大坑，因为微信早就调整了策略：从基础库2.10.0开始，wx.getUserInfo传入参数后返回的数据变成了匿名信息，真实头像昵称已经拿不到了。现在微信推荐的方式是“头像昵称填写能力”。

具体实现是用两个组件：头像用button组件设置open-type="chooseAvatar"，昵称用input组件的type="nickname"。用户在点击头像按钮时会唤起微信的头像选择面板，选完会返回一个临时的头像文件路径。昵称输入框则会唤起微信的昵称填充面板，用户可以直接选择自己的微信昵称。

这是一个典型的个人资料编辑页写法：

<!-- pages/profile/profile.wxml --> <button class="avatar-wrapper" open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar"> <image src="{{avatarUrl}}" /> </button> <input type="nickname" placeholder="请输入昵称" value="{{nickname}}" bindinput="onNicknameInput" />

Page({ data: { avatarUrl: '/images/default-avatar.png', nickname: '' }, onChooseAvatar(e) { // e.detail.avatarUrl是临时路径，需要上传到自己服务器 const tempFilePath = e.detail.avatarUrl; // 上传文件，拿到上传后的url this.setData({ avatarUrl: tempFilePath }); }, onNicknameInput(e) { this.setData({ nickname: e.detail.value }); } });

这里有个容易被忽略的点：chooseAvatar返回的是本地临时文件路径，这个路径只能在当前小程序本次运行期间使用。如果需要长期保存，必须把这张图片上传到自己的服务器或对象存储里，拿到图片的外链地址后存入数据库，下次直接从服务器拉取。上传图片时用wx.uploadFile，这个接口需要你后端专门写一个上传接口。

3.2 手机号获取：从getPhoneNumber到手机号快速验证组件

手机号授权也是重头戏。早期小程序开发者用的是button open-type="getPhoneNumber"，绑定事件后拿encryptedData和iv给后端解密，后端用session_key解密出手机号。但这个方式现在也逐渐被替代，微信推出了“手机号快速验证组件”。

手机号快速验证组件也是一个button，设置open-type="getPhoneNumber"，但在新版基础库里表现不同。用户点一下，系统会弹出微信官方验证面板，用户确认后，前端拿到一个code，然后把code传给后端，后端调用微信的接口换取手机号。原来的encryptedData解密方案正在被淘汰。

代码大概是这样的：

<button open-type="getPhoneNumber" bind:getphonenumber="onGetPhoneNumber">获取手机号</button>

onGetPhoneNumber(e) { if (e.detail.code) { // 把code传给后端，后端调用接口换取手机号 request('/auth/phone', 'POST', { code: e.detail.code }) .then(res => { this.setData({ phone: res.phone }); }); } else { // 用户拒绝授权或取消 wx.showToast({ title: '需要手机号才能继续', icon: 'none' }); } }

后端拿到手机号code之后，需要调用微信的getuserphonenumber接口，Request由https://api.weixin.qq.com/wxa/business/getuserphonenumber构成，带上access_token和code参数。这里注意，接口返回的手机号是明文，不会像以前那样需要session_key解密，整体流程简洁了不少。

手机号获取属于高敏感权限，微信审核很严格。如果你的小程序没有必须用手机号的业务场景（比如需要身份验证才能下单），建议不要强行收集。审核时微信会检查你的隐私协议里有没有声明收集手机号，以及是否真的有必要收集。我在一个社区团购项目里就遇到过审核被拒，原因是用户没有下单也弹窗要手机号。后来改成“用户点击下单时才弹出授权”，审核才通过。

3.3 个人信息存储与展示：脱敏是底线，别和我说数据库没被拖过

很多开发者会把用户手机号、真实姓名、身份证甚至地址原样返回给前端，这是在给自己埋雷。小程序个人信息页面的展示逻辑，除了正常功能需要，还要坚持一个原则：能不全量展示就不全量展示，能脱敏就脱敏。

手机号脱敏是基本操作。返回给前端时只保留前三位和后四位，中间用星号占位。如果用户需要完整手机号用于编辑或绑定其他账号，可以再走一次短信验证码校验。虽然这样麻烦一点，但能降低数据泄露后的损失。

头像和昵称相对敏感程度低一些，但也要注意用户主动修改过的昵称里可能包含特殊字符，输出到页面前要做好转义。后端要限制昵称长度（比如20个字符），防止用户输入超长内容导致页面布局错乱。头像上传时也要校验文件类型和大小，防止用户传了超大图片打爆服务器。

我常用的用户表设计大致是这样的：

手机号加密存储是必须的。即使你的数据库不小心被脱库，明文手机号直接暴露就是重大事故。我一般用AES加密，密钥放在服务端配置里。查询时解密后再脱敏返回给前端。另外，日志里也不要打印完整手机号，可以用脱敏后的字符串代替。

4. 登录与个人信息模块的常见问题排查

4.1 登录时code无效、频繁重新登录

code无效这个问题出现的概率很高，先确认是不是下面几个原因：

第一，code被使用过了。wx.login返回的code只能换一次session_key，同一个code如果前端因为请求超时重新发送，第二次肯定失败。前端要做好防重复提交，后端接口也要做幂等处理。第二，code过期。wx.login的code有效期只有5分钟，用户长时间停留在登录页不提交，回头提交就会过期。第三，appid和secret不匹配。如果你在小程序后台的开发者ID复制错了，或者secret被重置过，也会导致登录失败。

频繁重新登录的常见场景是：用户把小程序切到后台一段时间后再回来，token过期了，前端自动跳登录页重新走wx.login。这个逻辑本身没问题，但要注意跳转前把当前页面的路由记录下来，重新登录成功后不要回到登录页，而是回到用户刚才的操作页面。不然用户点一下某个功能，突然被甩到登录页，登录完又回到首页，之前的操作全丢了，体验会非常差。

我踩过一个隐蔽的坑：后端在生成token时用了JWT的过期时间，但前端的请求封装里把Authorization头拼错了，少了一个空格，导致后端解析不到token，每次都返回401。这种问题排查起来特别浪费时间，后来我习惯在封装的请求函数里把最终发送的头打印出来，一眼就能定位。

4.2 头像昵称填写不生效

在新版头像昵称组件里踩过两个坑，这里必须提一下。

第一个坑是button的open-type="chooseAvatar"在某些低版本基础库上不生效。微信的基础库版本迭代慢，用户手机上的微信可能还是老版本，低版本不支持新组件。解决办法是在调用前判断基础库版本，如果不支持就给用户展示普通的图片上传入口，让用户自己从相册选头像，昵称用普通input。这套降级方案不复杂，但能救回一批用老版本微信的用户。

第二个坑是昵称input的type="nickname"在部分安卓机型上不会弹出昵称填充面板，而是弹出了普通键盘。这个我暂时没有找到完美的兼容方案，只能接受，因为微信键盘组件的行为我们无法干预。遇到这种情况，用户手动输入昵称完全没有问题，只是少了一点便捷性。

另外一定注意：头像上传后，小程序前端展示的临时路径和后端返回的URL要分开保存。不要在setData里直接用一个值当两种用途。我见过一个项目，把本地临时路径存进数据库，结果其他用户访问的时候图片全部裂了，因为临时路径带上本地的file://协议，别人根本访问不了。

4.3 手机号解密失败或者获取不到手机号

新版手机号快速验证组件主要用code换取手机号，所以后端多了一个获取access_token的前置步骤。调用getuserphonenumber接口时需要access_token，这个access_token是依靠appid和secret调用https://api.weixin.qq.com/cgi-bin/token获得的小程序全局调用凭证。access_token有效期默认2小时，你应该在后端缓存起来，而不是每个获取手机号的请求都重新去拿。

用code换手机号时，需要注意code有没有过期，这个code和登录code不是同一个东西，不能混用。我刚开始接这个接口时就犯过糊涂，把登录用的wx.login code直接传给后端换手机号，结果接口一直报错。后来发现手机号code是从getPhoneNumber的e.detail.code里拿的，两者完全不同。

如果手机号获取到的是空串，先检查用户在弹窗里是否取消了授权。还有一个可能：你的后端传给微信的code是前端base64转码后的结果，微信不认这种格式，必须用原文。调试时把code打出来，看长度和格式是否正常。

4.4 个人信息页面的隐私保护指引配置

小程序在2023年之后对隐私协议的要求越来越严格。如果你的代码里使用了wx.getUserProfile、wx.getPhoneNumber或者wx.chooseAvatar等接口，都需要在小程序后台“用户隐私保护指引”中声明对应的信息类型。如果声明缺失，开发版调用相关接口时会直接报错，提示你未配置隐私政策。

实际操作中，我习惯把这些事情全部提前配好，而不是等审核时被拒再补：

• 在微信公众平台 -> 设置 -> 服务内容声明 -> 用户隐私保护指引，按照提示勾选需要收集的信息类型，比如“手机号”“头像”“昵称”“位置信息”等。
• 如果涉及收集手机号，必须在小程序内提供明显的隐私政策入口，通常放在“我的”页面底部。
• 首次启动小程序时，不要一进场就弹隐私授权框，这样很容易导致用户反感，也容易被审核盯上。应该在实际用到某个能力时再弹授权。

你的隐私政策文案也要写清楚：收集了什么信息、用来干什么、是否共享给第三方、如何注销账号。注销功能现在也变成刚需了，很多小程序因为没做注销功能而被拒审。我建议在个人信息页面放一个“注销账号”入口，用户申请后后端把openid关联的数据标记为注销状态，同时清理token。

5. 登录模块扩展场景：多小程序登录态打通与账号绑定

5.1 用unionid打通同一用户在不同小程序的账号

如果你后面做多小程序矩阵，比如一个生鲜小程序、一个社区团购小程序、一个会员商城小程序，同一个用户可能在这些小程序里各有一套openid。如果你想让他用同一个账号，就得靠unionid。

前提是你的小程序都绑到了同一个微信开放平台账号下。调用jscode2session接口时，如果用户已经在同一个开放平台下的其他小程序里授权登录过，返回的数据里会包含unionid。后端拿到unionid后，可以在用户表里做个唯一索引。新用户注册时先检查unionid是否存在，存在就直接延续老账号信息。这样用户切到你的另一个小程序时，头像、昵称、积分甚至订单都继承了。

不过要注意，unionid不是所有场景都会返回。如果小程序没有绑定开放平台，或者用户还没在开放平台下任何一个应用里暴露过unionid，第一次返回可能为空。所以我基本都是强制登录后主动检查，如果unionid为空就记录到日志，等下次登录再补。

5.2 第三方账号绑定与解绑的设计要点

某些业务小程序还需要支持手机号+验证码或者绑定其他平台账号（比如企业微信、钉钉）。这时候登录模块就不能只依赖微信小程序自带的能力，而是需要后端做一套“用户身份关联”逻辑。

我通常会设计一张user_account_bind表，字段包括id、user_id、bind_type（微信、手机号、企业微信等）、bind_value（openid或手机号）、created_at。这样同一个用户ID可以关联多个身份。登录时，不管用户拿哪种身份来，最终都换算成一个user_id，然后下发token。优点是灵活，缺点是查询链路过长，需要注意索引优化。

解绑操作更敏感，除了要校验当前登录态，还要判断解绑后用户是否还有可用登录方式。比如用户只剩一个微信绑定并且没有手机号，把微信解绑了，那这个账号就再也登不上去了，数据直接变成死数据。所以要加一道“最后一种登录方式不可解绑”的校验。

这一块其实和我的个人信息页面强关联，因为绑定列表就展示在“账号与安全”页面里，每个绑定项后面带着“解绑”按钮。设计时要把用户引导写得明白一些，避免用户误解解绑等于注销。

5.3 登录模块的性能与安全加固建议

登录接口是整个小程序的入口，一旦被刷，影响的是所有用户。我做过的项目里，登录接口被机器人刷过，一晚上生成几千个垃圾账号。后来加了防刷策略，主要有三点：同一个IP频率限制（比如每分钟最多10次登录请求）、同一个code禁止重复使用、注册时加一个简单的校验参数（比如前端通过某个接口获取的临时令牌）。

另外一个安全细节：后端接口要校验请求来源。小程序前端发过来的请求，Referer通常会带有https://servicewechat.com/，虽然这个头可以被伪造，但至少可以作为一道门槛。更严谨的做法是后端对特定接口要求带签名，前端对参数做hash后传给后端校验。登录接口这种关键路径，签名校验建议加上。

对于token的存储，小程序端用wx.setStorageSync存放，本身是安全的。但要注意不要在小程序里长期保存session_key。session_key是和小程序用户会话强相关的敏感密钥，换取手机号等场景的后端调用结束后，最好及时清理，不要一直存着，防止被其他业务误用。

6. 一些实操上的个人经验

登录模块这些代码写来写去，真正值钱的是踩坑后积累下来的体会。我最后分享几个个人经验，希望对正在写的人有帮助。

第一，登录接口要尽早设计成可扩展的。从一开始就不要只写死微信登录这一种方式，哪怕目前只用微信登录，接口也最好叫/auth/login，后面加手机号登录、账号密码登录时不用改接口名，而是在请求体里加一个loginType字段。我见过很多前端项目，每个登录方式都单独写一个接口，到了后期越来越难维护。

第二，个人信息更新接口要做全字段校验。很多开发者只校验了token，没校验昵称是否包含敏感词、头像URL是否合法、手机号是否重复。后端的校验逻辑一定要比前端严格，毕竟前端校验只是提升体验，后端校验才是安全防线。

第三，关于日志。不要在日志里打印完整手机号、openid、session_key、token。我踩过一次教训，联调时为了方便把session_key打到了日志里，后来日志平台被其他人翻到，虽然没造成事故，但心里特别不踏实。坚持把敏感字段脱敏后再打印，是最好的习惯。

第四，个人信息页面加载头像时要考虑图片404的问题。用户很久没登录，之前上传的头像被清理了，前端拉取头像可能返回404。页面要有默认头像兜底，不然用户打开个人信息页一片空白，还以为是bug。

第五，小程序后台的开发者工具调试时需要注意“不校验合法域名”开关。本地开发时为了方便可以打开，但提交体验版和正式版之前一定要关掉，并且在小程序后台配置好服务器域名。很多人登录接口报错，就是因为忘了配request合法域名，微信拦截了请求。

微信小程序的登录模块和个人信息能力，是每个小程序开发者的必修课。尤其是个人信息这块，合规底线一旦踩破，不只是审核被拒的问题，还有可能引发用户投诉和法律风险。所以设计时一定要把“最小收集”放在第一位：能不要的信息就不要，必须收集的信息就明确告知、安全存储、按需展示。代码写得再漂亮，安全上漏了也是白搭。希望这篇内容能让你少走几步弯路。