
「南京小程序登录与用户身份怎么设计」可以收敛成一条固定链路:前端调用 wx.login 拿到临时凭证 code,服务端带 appid、secret、code 请求 auth.code2Session,换回 openid、session_key,以及满足条件时的 unionid,最后由服务端签发业务自己的登录态。头像昵称、手机号、隐私保护指引都挂在这条链路的不同位置,不属于登录动作本身。下面按字段语义、链路时序、凭证约束、跨应用标识、授权边界、故障定位逐段拆开,每段给出可直接套用的核对表与留档项;接口规则、计费标准与类目范围会调整,实现时以微信开放文档和微信公众平台当期公示为准。
把判断放在前面:登录出问题时,多数不是接口写错,而是把四个字段当成同一种「用户 ID」混用,或者把 code、session_key 当成可以长期保存的登录态。openid 只回答「这个人在当前小程序里是谁」,unionid 才回答「这个人在同一开放平台账号下的其它应用里是谁」,session_key 是服务端用于解密与校验的密钥,code 是一次性、有时限的临时票据。四者的产生环节、生效范围、存放位置都不同,混用会直接带来跨端重复账号、解密失败、登录态莫名片失效。
一、四个字段分别回答什么问题
接手一个已有小程序时,建议先把用户表里与身份相关的列全部列出来,逐一对照下表归位。这张表可以直接当作代码评审的检查项,每一行都对应一类高频故障。
| 字段 | 产生环节 | 唯一性或生效范围 | 应存放位置 | 常见误用 |
|---|---|---|---|---|
| openid | auth.code2Session 返回 | 单个小程序内唯一,不同小程序之间不同 | 服务端用户表 | 拿它跨小程序、跨公众号关联同一用户 |
| unionid | 同一接口返回,需满足绑定条件 | 同一微信开放平台账号下的应用之间唯一 | 服务端用户表,作跨应用主键 | 未绑定开放平台时假定一定有值 |
| session_key | 同一接口返回 | 与一次登录会话绑定,会发生变化 | 仅服务端缓存或会话存储 | 返回给前端、写入日志、当作用户标识 |
| code | wx.login 在前端获取 | 一次有效且有时限 | 只出现在「前端 → 服务端 → 微信」这一跳 | 落库、缓存复用、当作登录态存进 storage |
| 自定义登录态 | 服务端自行签发 | 由业务系统自己定义有效期 | 前端本地缓存,请求时随带 | 与微信侧登录态、session_key 混为一谈 |

表里最容易被跳过的是「应存放位置」这一列。小程序代码包可以被解开,任何写死在前端的 AppSecret 都等同于公开;session_key 一旦下发到前端,加密数据的校验边界也就消失了。微信开放文档在小程序登录章节明确写出:会话密钥是对用户数据进行加密签名的密钥,开发者服务器不应该把它下发到小程序,也不应该对外提供这个密钥。
二、一次登录的完整链路
把链路排成固定五步,好处是下一次迭代或换人交接还能复用同一套口径。下表把每一步的调用方、输入、输出和约束写全,可以直接贴进接口文档。

| 顺序 | 调用方 | 输入 | 输出 | 关键约束 |
|---|---|---|---|---|
| 1 取临时凭证 | 小程序前端 | wx.login() | code | 不缓存、不落库、不写进日志 |
| 2 换取凭证 | 开发者服务器 | appid + secret + code | openid、session_key,以及满足条件时的 unionid | 必须由服务端发起,secret 不出现在前端 |
| 3 保存会话密钥 | 开发者服务器 | session_key 与 openid 的对应关系 | 按用户维度隔离的服务端会话 | 只存服务端,不随任何响应返回 |
| 4 签发业务登录态 | 开发者服务器 | openid 查业务用户表 | 业务 token 或 sessionId | 与微信侧登录态解耦,自定有效期与续期策略 |
| 5 校验登录态 | 小程序前端与服务端 | wx.checkSession() 加业务 token 校验 | 有效或需重新登录 | 失效时重新 wx.login 取新 code,不重试旧 code |
第 4 步常被省略,却是整套设计里最值得单独写清楚的一步。微信维护的登录态对开发者透明,业务系统签发的登录态由自己负责,两者不是同一件事。把它们分开之后,token 过期策略、多端登录、用户体系改造都不会反过来改动登录链路;反过来,若直接把 code 或 openid 当 token 用,五分钟之后全线失效几乎是必然结果。
三、code 与 session_key 的硬约束
这一节可以当作故障速查表。左列是约束,右列是违反之后的实际现象与收敛动作,排查时从现象反查约束通常比逐行读代码快。
| 约束 | 官方口径 | 违反后的现象 | 处置动作 |
|---|---|---|---|
| code 只能使用一次 | 临时登录凭证 code 只能使用一次 | 重复提交返回 code 已被使用一类的错误,典型如 40163 | 让前端重新 wx.login 取新 code,不重试旧值 |
| code 有时限 | 有效期约 5 分钟,具体时效由微信维护、对开发者透明 | 换取凭证失败、偶发登录不成功 | 换取失败统一收敛到重新登录出口 |
| secret 只在服务端 | code2Session 需要 appid 与 secret,属服务端调用 | 前端硬编码等同于公开,代码包可被解开 | 用服务端环境变量或配置中心注入,禁止打进代码包 |
| session_key 不下发 | 官方文档明确不应下发小程序、也不对外提供 | 解密与签名校验边界失效 | 服务端按用户维度保存,前端只拿业务 token |
| 登录态需自检 | wx.checkSession 用于检测当前用户登录态是否有效 | 静默使用已过期登录态,关键操作偶发失败 | 关键操作前校验,失效则重新走完整链路 |
| 会话密钥会变化 | session_key 与一次会话绑定,重新登录、长时间未使用等情形会变化 | 解密失败、加密数据校验不通过 | 重新换取,不尝试续用旧 session_key |
一个可复用的做法是:把 code 当作「一次性票据」而不是「身份」,把所有换取失败都收敛到「重新 wx.login」这一个出口。并发场景里同一页面多个请求各自拿 code 去换,只有一个会成功,与其给旧 code 加重试,不如让多个请求共用一个进行中的登录任务。
四、unionid 什么时候才有
「小程序获取 unionid 失败是什么原因」这类问题,优先查的往往不是代码,而是开放平台账号的绑定关系。下表按场景列出是否返回、前置条件与排查动作。
| 场景 | 是否返回 unionid | 前置条件 | 排查动作 |
|---|---|---|---|
| 小程序已绑定微信开放平台账号 | 是 | 绑定关系存在于开放平台,主体信息一致 | 在开放平台核对绑定主体与小程序 appid |
| 未绑定开放平台账号 | 否 | 无 | 先完成绑定,再重新换取凭证 |
| 用户在同一开放平台下多个应用使用 | 各应用拿到同一个 unionid | 应用归属同一开放平台账号 | 用 unionid 做跨应用主键,不要拼接 openid |
| 只做单个小程序且无跨端需求 | 可能有值但用不上 | 无 | 用 openid 即可,不引入额外依赖 |
| 公众号、小程序、移动应用要打通 | 需要 | 全部绑定到同一开放平台账号 | 逐一核对每个应用的绑定状态与主体 |
同一个微信用户在不同小程序里的 openid 一定不同,这是设计使然,不是接口异常。只要出现「换了个小程序就多出一个账号」,基本可以确定跨应用关联用的字段选错了。绑定状态属于后台配置,代码里无论怎么重试都不会让它变成有值。
五、头像昵称、手机号与隐私指引的边界
登录是静默的,头像昵称和手机号需要用户主动操作,隐私指引是后台配置项,位置、相册等能力另走 scope 授权。把这几件事全塞进一个「一键登录」按钮,既拿不到数据,也容易在审核环节被退回。

| 能力 | 现行方式 | 关键限制 | 核验位置 |
|---|---|---|---|
| 微信身份登录 | wx.login 配合 auth.code2Session | 静默完成,不需要用户点授权 | 微信开放文档「小程序登录」 |
| 头像昵称 | 「头像昵称填写能力」,chooseAvatar 按钮与 nickname 输入框 | 自 2022 年 10 月 25 日 24 时起(后延期至 11 月 8 日 24 时)wx.getUserProfile 被收回,生效期后发布的新版本统一返回默认灰色头像与「微信用户」;插件侧 wx.getUserInfo 同样调整;填写能力自基础库 2.21.2 起支持 | 微信开放社区《小程序用户头像昵称获取规则调整公告》 |
| 手机号 | 手机号快速验证组件或实时验证组件,前端拿到动态令牌 code,服务端用 phonenumber.getPhoneNumber 换取 | 面向非个人且已完成认证的小程序;快速验证不承诺实时性;自 2023 年 8 月起按次计费,快速验证标准单价 0.03 元每次成功调用、实时验证 0.04 元,每账号有 1000 次体验额度,部分主体类型免费 | 开放文档「手机号快速验证组件」与公众平台「付费管理」 |
| 用户信息处理 | 后台配置《小程序用户隐私保护指引》,声明涉及的信息类型,调用相关接口前完成授权 | 指引声明与实际调用的接口清单不一致,会影响审核与接口调用 | 公众平台「用户隐私保护指引」与开放文档隐私相关接口 |
| scope 授权 | 位置、相册、录音等按 scope 单独申请,配合 wx.getSetting 与 wx.authorize | 与登录授权是两套,不因已登录而自动获得 | 微信开放文档「授权」章节 |
头像昵称那一行尤其容易踩到历史代码:旧教程里普遍用 getUserProfile 拉取头像昵称,直接搬到新版本就会得到灰色头像。手机号那一行则是成本项,计费口径、免费主体范围与体验额度都可能调整,落地前宜在公众平台「付费管理」里核一遍当期数值,再决定是否真的需要在注册环节收集手机号。
六、常见故障按链路定位
把现象翻译成链路上的具体一段,再取证,比反复清缓存有效。下表按报错或表现反查优先检查项。
| 现象 | 优先检查 | 依据 |
|---|---|---|
| 换取凭证返回 code 已被使用 | 是否重复提交同一个 code、是否存在并发换取 | code 只能使用一次 |
| 换取凭证返回 code 无效 | code 是否超时、appid 与 secret 是否属于当前小程序 | code 有时限且与小程序凭证绑定 |
| 偶发解密或签名校验失败 | session_key 是否已变化、服务端是否按用户维度隔离存储 | 会话密钥与一次会话绑定 |
| 跨小程序出现重复账号 | 是否拿 openid 做跨应用关联 | unionid 才是开放平台账号内的唯一标识 |
| 拿不到 unionid | 微信开放平台账号的绑定状态 | 绑定后才返回该字段 |
| 手机号换取失败 | 动态令牌是否只用一次、主体是否完成认证、额度是否用尽 | 组件与服务端接口文档 |
| 审核或接口提示隐私相关 | 指引声明的信息类型与实际调用的接口清单是否一致 | 用户隐私保护指引配置 |
| 用户点了登录没反应 | 是否把授权弹窗逻辑写进了 wx.login 流程 | 登录本身是静默的,不弹授权窗 |
七、上线前自检清单
这份清单把「登录做完了」变成可交付的记录,每一项都能对应到一次请求、一条配置或一个页面操作,交接和复查时不用重新猜。
- 前端全局搜索 AppSecret,确认代码包、构建产物与配置里没有硬编码。
- 抓取一次完整登录请求,确认 code 只在换取链路出现一次,日志里没有明文。
- 确认 session_key 不出现在任何返回给前端的响应体中,也不写进可导出的日志。
- 确认业务 token 有明确有效期与续期路径,且校验逻辑不依赖 session_key。
- 在微信开放平台核对小程序绑定状态,并按是否存在跨应用需求决定是否使用 unionid。
- 用两个不同小程序、同一个微信账号各登录一次,记录 openid 是否不同、绑定后 unionid 是否一致。
- 逐项比对《小程序用户隐私保护指引》声明的信息类型与实际调用的接口清单。
- 真机走一遍登录、头像昵称填写、手机号获取,并额外覆盖一台低版本微信客户端,记录基础库版本与结果。
八、常见问题
问:unionid和openid的区别
答:openid 是同一个微信用户在单个小程序内的唯一标识,换一个小程序就不同;unionid 是同一微信开放平台账号下跨应用唯一的标识。只做单个小程序用 openid 即可,需要打通公众号、其它小程序或移动应用时才用 unionid,且前提是这些应用都绑定到了同一个开放平台账号。
问:怎么获取小程序的unionid
答:先把小程序绑定到微信开放平台账号,再由服务端调用 auth.code2Session;满足绑定条件时,返回结果里会带上 unionid。前端没有单独「获取 unionid」的接口,它随登录凭证一起返回,不应在前端解析或保存。
问:小程序获取unionid失败是什么原因
答:按这个顺序查:开放平台账号是否完成绑定、绑定主体与小程序主体是否一致、调用的 appid 是否为当前小程序、换取请求是否由服务端带正确 secret 发起。绑定状态属于后台配置,代码里重试不会改变返回结果。
问:小程序code多久失效
答:临时登录凭证 code 有效期约 5 分钟,且只能使用一次,具体时效由微信维护、对开发者透明。换取失败时不要重试旧 code,应重新调用 wx.login 拿新 code;业务侧用 wx.checkSession 判断登录态是否仍有效。
问:小程序授权登录流程是什么
答:标准流程是 wx.login 取 code、服务端 code2Session 换 openid 与 session_key、服务端保存会话密钥、签发业务登录态、关键操作前用 wx.checkSession 校验。需要注意微信身份登录是静默的,头像昵称与手机号属于另外的用户主动操作,不属于这条流程。
问:小程序用户隐私保护指引怎么填写
答:在微信公众平台后台按实际调用的接口逐项声明收集的信息类型、用途与使用范围,再对照代码里真实调用的位置、录音、相册、用户信息、手机号等接口清单核一遍。声明与实际不一致会影响审核与接口调用,后续新增接口时要同步更新指引。
问:微信小程序获取手机号授权登录的方法
答:现行方式是手机号快速验证组件或实时验证组件,由用户点击按钮后前端拿到动态令牌 code,服务端调用 phonenumber.getPhoneNumber 换取手机号。新版本组件不再要求提前调用 wx.login。该能力面向非个人且已完成认证的小程序,自 2023 年 8 月起按次计费,具体单价与免费范围以公众平台当期公示为准。
问:小程序登录信息过期怎么办
答:先用 wx.checkSession 判断当前登录态是否有效;失效就重新走一遍 wx.login 到 code2Session 的完整链路,并更新服务端保存的 session_key 与业务登录态。业务 token 的过期与续期由自己的服务端策略决定,两者分开处理,不要试图延长 session_key。
九、可复用的核验路径
把上面的判断落到三条可自行复现的路径。其一,打开微信开放文档的「小程序登录」与 auth.code2Session 页面,逐字段比对返回结构与注意事项,重点看会话密钥与临时凭证的约束。其二,在微信公众平台后台核对开放平台绑定状态、用户隐私保护指引、付费管理里的实际配置,这三项都是后台事实,不随代码变化。其三,用两台真机、两个小程序、同一个微信账号做一次跨应用登录对照,把实际拿到的 openid 与 unionid 记进测试记录。接口规则、计费标准与主体范围会调整,任何实现以平台当期公示与后台实际显示为准。
配图说明:本文部分配图使用人工智能生成合成技术制作。





