微信小程序登录页面全解析：从wx.login到登录态维护

做过小程序登录页的人应该都经历过这种循环：打开官网文档，照着 wx.login 抄一段，真机一跑，openid 拿到了，可用户昵称和头像却越来越难拿；好不容易把授权弹窗调出来，又想不通为什么同一套代码在微信版本不同的手机上表现完全不一样。我前前后后做了几十个小程序的登录模块，可以很直接地说，登录页是目前整个小程序项目里最“低门槛、高隐藏复杂度”的一环，它既是用户对产品信任的起点，也是后面支付、推送、客服消息等能力的前置依赖。

这篇文章不打算复述一遍官方文档，而是想围绕“微信小程序登录页面”从方案选型、页面实现、异常排查到合规边界，把我实际操作中验证过的东西一次讲清楚。适合刚接触小程序不久、想直接抄一套登录方案的新手，也适合已经上线过几个项目、但还时不时被用户信息拿不到、登录态过期、真机报错这些细节绊住的开发者。

1. 登录不是“一个页面”，是整个用户体系的入口

很多开发者的第一直觉是：登录页面无非就是放一个“微信一键登录”按钮，用户点了之后把 code 发给后端，后端返回一个 token，然后跳转首页。这么理解不算错，但一旦你把登录这个动作窄化成“一个页面”，后面大概率会遇到两类麻烦：一是用户信息不完整，二是不同业务场景下登录逻辑越写越乱。

1.1 三种登录模式，别上来就全用

小程序里的“登录”其实有三种完全不同的形态，很多人混着用，最终接口和页面状态全纠缠在一起。

第一种是静默登录，也就是最纯粹的 wx.login。它不弹任何授权框，只返回一个临时 code，后端拿 code 到微信服务端换 openid 和 session_key。这种方式能识别用户身份，但拿不到昵称、头像这些资料，适合只需要知道“你是谁”而不需要展示个人资料的产品，比如工具类小程序、企业内部应用。静默登录应该放在小程序启动阶段自动执行，用户无感，转化率损失最小。

第二种是用户信息授权登录，通过 wx.getUserProfile 或者按钮的 open-type="chooseAvatar" 这类能力，让用户主动提交头像和昵称。它比纯静默登录多了一步用户交互，适合社区、内容类产品，用户需要在页面上露出头像昵称的。

第三种是手机号快速验证登录，使用 <button open-type="getPhoneNumber"> 获取微信绑定的手机号，后端通过 phonenumber.getPhoneNumber 解密得到真实手机号。这是现在电商、生活服务类小程序的主流，因为手机号意味着更强的账号关联和风控能力。

三种模式没有谁绝对好，关键是分清场景。我在项目里最常见的设计是：启动时先静默 wx.login，拿到临时身份；如果用户后续需要展示头像昵称或手机号，再在具体页面上触发对应的授权能力。而不是把静默登录、用户信息授权全部堆在同一个登录页上一股脑执行，那样用户会被连续几个弹窗吓跑。

1.2 2021年之后的头像昵称变更：你不能再把 getUserInfo 当万能钥匙

如果你做过老版本的小程序，一定记得早期用 wx.getUserInfo 配合 button open-type="getUserInfo" 就能拿到用户头像、昵称的“完整版”。但从2021年开始，微信陆续调整了用户信息相关接口：wx.getUserInfo 不再返回真实的头像和昵称，默认返回灰色头像和“微信用户”这类脱敏数据；新一代的获取方式是让用户主动填写昵称、主动选择头像，也就是头像昵称填写能力。

这个变化直接改变了登录页的交互逻辑。以前你可以在登录页上放一个“获取微信信息”的按钮，点一下弹个授权框，用户同意后头像昵称自动填充。现在不行了，你需要在登录页上提供独立的“选择头像”和“输入昵称”入口，比如用 button open-type="chooseAvatar" 唤起头像选择，用 <input type="nickname"> 唤起微信键盘里的昵称填充。很多开发者没意识到这一点，还在网上找老代码，结果真机上头像昵称永远拿不到，还以为是自己写错了。

所以我的建议是：登录页的设计要回归到“身份识别”本身，把用户资料收集拆成独立步骤，不要在用户第一次进来时就强求所有信息。wx.login 负责识别身份，头像昵称交给用户主动提供，手机号在需要时再触发，一层一层推进，体验反而干净。

2. 一个能直接抄作业的登录页实现

说完了理念，下面给出一套我实际在项目里用过的登录页实现。这套方案以“静默登录 + 自定义登录态”为主，兼容头像昵称填写和隐私协议弹窗，适合大多数中小型小程序项目直接改改落地。

2.1 页面结构与隐私协议区域

登录页的核心结构，一般包括品牌区、微信登录按钮、协议勾选区域。协议勾选千万不要省，也不要把 wx.login 放到用户勾选协议之前。这也算是我踩过一个坑：早期版本在小程序启动时就静默 wx.login 并请求后端登录接口，结果被平台提示隐私协议未同意就收集用户信息，后来改成了用户点击登录按钮时才触发 wx.login，并前置弹出隐私弹窗。

先看 WXML 结构：

xml复制<view class="login-page">
  <view class="login-header">
    <image class="logo" src="/assets/logo.png" mode="aspectFit" />
    <text class="app-name">某某服务</text>
  </view>

  <view class="login-form">
    <button
      class="primary-btn"
      loading="{{loading}}"
      disabled="{{loading}}"
      bindtap="handleLogin"
    >微信一键登录</button>

    <view class="agreement">
      <checkbox-group bindchange="handleAgreementChange">
        <checkbox value="agree" checked="{{agreed}}" color="#07c160" />
      </checkbox-group>
      <view class="agreement-text">
        <text class="link" bindtap="openPrivacy">《用户协议》</text>
        <text>和</text>
        <text class="link" bindtap="openPrivacy">《隐私政策》</text>
      </view>
    </view>
  </view>
</view>

这里的关键是协议勾选状态与登录按钮的联动。没有勾选协议时，点击登录直接 toast 提示，而不是继续执行 wx.login。后端此时也不应该收到任何请求。协议内容的查看建议调用 wx.openPrivacyContract，它是微信官方提供的隐私协议展示能力，比自己在 WebView 里加载一个页面要容易满足审核要求。

2.2 登录按钮逻辑：防重、loading 与错误提示

登录按钮的点击处理，我习惯写成下面这样，所有异常都收敛到 try/catch 里，避免用户看到一堆看不懂的报错：

javascript复制Page({
  data: {
    loading: false,
    agreed: false
  },

  handleAgreementChange(e) {
    this.setData({ agreed: e.detail.value.length > 0 });
  },

  openPrivacy() {
    // 打开隐私协议，等价于 wx.openPrivacyContract
    wx.openPrivacyContract({
      fail: () => {
        wx.showToast({ title: '请在右上角设置中查看', icon: 'none' });
      }
    });
  },

  async handleLogin() {
    if (!this.data.agreed) {
      wx.showToast({ title: '请先阅读并同意协议', icon: 'none' });
      return;
    }
    if (this.data.loading) return;

    this.setData({ loading: true });

    try {
      const { code } = await wx.login();
      const res = await new Promise((resolve, reject) => {
        wx.request({
          url: 'https://your.domain.com/api/login',
          method: 'POST',
          data: { code },
          success: resolve,
          fail: reject
        });
      });

      if (res.data && res.data.token) {
        wx.setStorageSync('token', res.data.token);
        wx.switchTab({ url: '/pages/index/index' });
      } else {
        wx.showToast({ title: res.data.message || '登录失败，请重试', icon: 'none' });
      }
    } catch (err) {
      console.error('login error:', err);
      wx.showToast({ title: '网络异常，请稍后重试', icon: 'none' });
    } finally {
      this.setData({ loading: false });
    }
  }
});

loading 字段同时控制按钮的 loading 和 disabled，这是防止用户连续点击导致后端收到多个 code 的常规手段。另外我没用 wx.navigateTo 跳首页，因为登录成功后的页面通常是小程序的 tabBar 页面，navigateTo 不能跳 tabBar 页面，必须用 switchTab。这一点经常有人忽略，改了半天发现页面跳不过去，控制台报一个 “can not navigateTo a tabbar page”。

2.3 后端用 code 换登录态的完整流程

前端拿到 code 之后，后端要做的事是：用 appid 和 secret 调用微信接口 https://api.weixin.qq.com/sns/jscode2session，把 code 换成 openid 和 session_key。这一步有一个业界通用的原则：secret 绝对不能放在小程序前端代码里，只能在服务端保存。前端只负责传 code，后端负责跟微信服务器通信。

下面是一段 Node.js 风格的伪代码，核心逻辑很清晰：

javascript复制const axios = require('axios');

async function code2Session(code) {
  const { data } = await axios.get('https://api.weixin.qq.com/sns/jscode2session', {
    params: {
      appid: '你的appid',
      secret: '你的secret',
      js_code: code,
      grant_type: 'authorization_code'
    }
  });

  // data: { openid, session_key, unionid, errcode, errmsg }
  if (data.errcode) {
    throw new Error(`code2Session failed: ${data.errcode} ${data.errmsg}`);
  }

  return data;
}

拿到 openid 和 session_key 后，后端建议自己生成一个业务 token（比如 JWT 或随机字符串），与用户 ID 绑定后返回给前端。session_key 不要直接返回前端，也不要在前端存储，它只在后端解密手机号、获取微信开放数据时使用。前端后续请求都带这个业务 token，后端不再需要每次调微信接口确认身份，这样能大幅减少依赖微信接口的网络耗时和潜在限流。

wx.login 返回的 code 有效期很短，一般只有几分钟，而且只能用一次。如果后端返回 40029 之类的错误码，多半是 code 重复使用或已经过期。后面会专门讲异常排查。

2.4 样式细节：适配 iPhone 底部安全区与不同屏幕

登录页的样式不复杂，但还是有几个容易踩坑的点。我在线上项目里最常遇到的问题，是不同机型上按钮位置和顶部 logo 高度不一致。建议登录页不是用 flex-direction: column 从顶部往下排，而是把品牌区放在视觉中上部，登录按钮和协议固定在下半部分，并且确保底部按钮避开 iPhone 的 home indicator。

CSS 里可以直接这样处理：

css复制.login-page {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
  background-color: #fff;
  padding-bottom: calc(env(safe-area-inset-bottom) + 24rpx);
  box-sizing: border-box;
}

env(safe-area-inset-bottom) 是适配底部安全区的关键。如果没有这一句，用户会看到登录按钮被 iPhone 底部的横条挡住，体验很差。顶部导航栏高度也是很多人在意的点，尤其登录页如果要自定义顶部标题，建议用 wx.getSystemInfoSync() 获取状态栏高度，再通过 CSS 变量传入，而不是在样式里写死 20px 或 40px。不同手机状态栏高度差异很大，写死必出问题。

3. 登录页上线前必须处理的异常与边界

登录页最容易翻车的地方不在功能走通，而在边界情况。下面这些异常我基本都在真机上踩过，有些甚至是在生产环境被用户反馈之后才发现的。

3.1 真机调试网络失败：err_connection_reset 的排查链路

很多开发者在开发者工具里跑登录一切正常，一真机测试就报 net::err_connection_reset 或者 failed。这里先不要怀疑代码，而要按顺序排查。

最优先确认的是 域名白名单。小程序要求所有网络请求的域名必须配置在微信公众平台的“request 合法域名”里，而且必须是 HTTPS，不能直接使用 IP。开发者工具里可以勾选“不校验合法域名”，真机上没这个选项，所以后端接口域名要是没配就必然失败。还有一个小细节：如果你通过 IP 或 localhost 访问本地服务，真机自然连不上，因为手机访问不了你电脑上的 localhost。

如果域名已经配置却仍然连接重置，下一步检查服务器是否限制了 TLS 版本或证书链不完整。微信对 HTTPS 证书要求比较高，部分低版本手机或者证书中间链缺失都会导致握手失败。可以用在线工具检查证书链，确保服务器返回的证书是完整链，而不是只返回叶子证书。

最后要留意的是并发请求。有的 App 框架会在启动时同时发起多个请求，比如登录、配置拉取、更新检测，如果某个请求超时返回，可能会导致联调环境出现 err_connection_reset。建议登录请求独立封装超时时间，超时后重试两次，而不是直接抛给用户“网络异常”。

3.2 code2Session 常见报错与处理

code2Session 是我后端日志里出现频率最高的报错之一。常见错误码主要有这四个：

这里最隐蔽的问题是 code 被使用。比如前端网络抖动，请求发到了后端，后端处理超时，前端主动重试，这时同一个 code 会被后端接收两次，第二次必然失败。解决办法是把请求改成“幂等”：前端生成一个请求 ID，同一个登录流程只用同一个 code；后端即使收到重复请求，也返回同一个 token，不要重新调 code2Session。

3.3 用户拒绝授权、取消操作、二次进入的降级方案

手机号授权、头像昵称填写，用户都有可能拒绝。拒绝之后，页面不能卡死，也不能在用户下次点登录时又弹一次同样的授权框。

对于头像昵称，我建议在登录页上用“跳过”按钮做降级。用户如果不同意提供头像昵称，可以先用虚拟头像和默认昵称进入主流程，等到产品需要展示个人资料时再引导补全。微信的 chooseAvatar 和昵称输入框都必须在用户主动点击之后才能触发，所以不要试图在页面加载时自动唤起。

对于手机号快速验证组件，用户取消后，按钮会触发 fail 回调，里面 errMsg 会包含 “deny” 或者 “cancel”。这时候不要马上再弹，而是提供一个“暂不登录，随便逛逛”的入口。很多电商小程序会允许游客模式浏览商品，等到加购或下单时再强制登录，这种渐进式授权比第一屏就强索要资料友好得多。

4. 登录态的维护、续期与合规红线

登录不是一次请求就结束了，登录页背后其实是“登录态管理”和“合规授权”两条长链路。这两块做不好，即使页面看起来正常，后面也会遇到频繁掉线、审核被拒等麻烦。

4.1 自定义登录态 token 的管理与刷新

我见过不少项目把微信返回的 session_key 直接存到小程序本地，每个接口都拿它当凭证。这是有风险的，因为 session_key 的更新机制不是给你前端请求用的，一旦它过期，客户端没有任何能力自行刷新。

正确做法是引入自己的 token。小程序本地只存业务 token，后端通过签名或数据库 session 记录判断用户身份。尽量做到“小程序的登录态与微信登录态解耦”：业务 token 过期时间可以自己控制，比如 7 天有效，快到时间就自动续期，不需要用户重新走登录流程。

为了统一管理，我给项目封装了一个 request 方法，所有业务请求都走它：

javascript复制const request = (options) => {
  const token = wx.getStorageSync('token');
  return new Promise((resolve, reject) => {
    wx.request({
      ...options,
      url: `https://your.domain.com/api${options.url}`,
      header: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`
      },
      success(res) {
        if (res.statusCode === 401) {
          // token 失效，清除本地登录态并跳转登录页
          wx.removeStorageSync('token');
          wx.navigateTo({ url: '/pages/login/index' });
          reject(new Error('login expired'));
          return;
        }
        resolve(res);
      },
      fail: reject
    });
  });
};

这样处理之后，用户 token 过期时不会出现白屏或接口报错，而是自动回到登录页。如果产品要求“尽量静默续期”，可以加一个刷新 token 的逻辑：响应头里返回 x-new-token，前端每次请求都检查并根据需要覆盖本地 token，达到用户无感知续期。

4.2 隐私协议弹窗与 getPrivacySetting 合规检查

用户协议和隐私政策不是放一个链接就完事。微信平台对隐私协议的使用有明确要求，如果你在小程序里调用了微信提供的隐私相关接口，比如 wx.getUserProfile、wx.chooseMedia、wx.getPhoneNumber，就必须在小程序后台配置“用户隐私保护指引”，并在前端根据隐私授权状态决定是否要先弹出协议框。

实操上，有一个官方接口 wx.getPrivacySetting 用来查询用户对该小程序的隐私授权状态。如果用户尚未同意隐私协议，我们要引导用户点击隐私弹窗。弹窗的展示可以是自定义样式的半屏组件，内部包含“查看隐私协议”的链接和“同意/不同意”按钮。用户点了“同意”之后，前端调用 wx.requirePrivacyAuthorize 请求授权，然后才继续后续的登录逻辑。

我自己的经验是：不要在用户一进入小程序就立刻弹隐私协议，那样体验太重。可以等用户点击登录按钮、即将触发 wx.login 时再弹。有隐私协议授权失败的时候，多半是用户在前置弹窗点了拒绝，此时不能强制再弹，而是显示人工客服联系方式或引导用户通过右上角设置修改授权。

4.3 手机号一键登录：接入前先确认条件和成本

手机号快速验证组件虽然好用，但接入门槛比表面看起来高。getPhoneNumber 不只是前端一个按钮，后端需要配合微信服务端接口解密手机号，而且每次调用会有相应成本，个人主体小程序很多功能也受限。如果你的产品只是一个小工具，其实不需要一上来就接手机号登录，先用静默登录解决身份识别问题，等用户规模增长、业务确实需要手机号做二次验证时再接入。

真到了那一步，要特别注意按钮写法。open-type="getPhoneNumber" 的 bindgetphonenumber 回调里，e.detail.code 或 e.detail.errMsg 是核心。新版本微信推荐通过 code 换取手机号，而不是把 encryptedData 拿回来解密。这一块的接口变动比较频繁，以官方文档为准，但记住一个原则：手机号只是登录的补充手段，不是唯一路径，页面一定要保留“微信账号登录”等替代方式。

5. 从登录页延伸的实战心得

文章最后，不汇总知识点，只分享几个我从登录页项目里总结出来的实际判断。

第一个心得是，登录页的代码量虽然不大，但它往往是整个小程序最早启动、最容易被周围人拿来做“评估”的页面。用户打开小程序，如果登录页转圈三秒没反应，之后就算功能再好，留存也已经掉了一截。所以我把登录请求的超时时间设得比其他接口更短，一般 5 秒内，超时就提示并允许重试，而不是让用户一直看着 loader 空转。

第二个心得是，微信的登录能力这两年变动很多，比如头像昵称填写、手机号 code 换取、隐私协议弹窗，都是逐步收紧的过程。接到一个老项目时，一定要先检查当前登录流程用的是不是“已经被废弃能力”的写法，别在旧代码上硬改。每次踩到“为什么真机拿不到用户信息”的问题，先去看微信官方公告，更新频率远比你想象的高。

第三个心得是我自己的喜好：登录页尽量做成“可无感跳过”的页面。对很多新用户来说，第一次打开小程序就想让他乖乖点登录，本身就是反人性的。把登录做成“用的着才登”的流程，用户清楚知道为什么需要登录，转化率反而高。这个思路和微信推荐的能力方向是一致的：越来越少强制弹窗，越来越多用户主动触发。

最后一个建议，登录设计不要脱离后端。如果你只是前端出身，至少要和后端同事把 code 的传递、token 的过期策略、OpenID 的关联规则对齐。登录页看起来是前端的一亩三分地，实际上整个用户体系的地基都打在这一堆按钮和弹窗上，越早想明白，后面的坑越少。