uniapp微信小程序手机号获取：getPhoneNumber与code换取

上周帮一个做社区团购的朋友收尾项目，登录页卡在"一键获取手机号"上整整两天。他给我的截图里，前端代码写得没错，按钮、事件、回调全都照着网上那篇 2021 年的教程抄的，encryptedData和iv也确实打印出来了，可后端解密就是报41001。问题不在他写的代码上，而在于微信这套手机号获取机制在过去两年里换了底层链路，网上能搜到的大部分教程还在讲session_key解密那条老路，抄下来自然处处漏风。

这篇就把微信小程序里获取用户手机号这件事，按我们团队真实项目里跑通的顺序完整捋一遍：老方案为什么必须换、前置资质和隐私协议这两个最容易翻车的点怎么处理、uniapp 端按钮到底怎么写、服务端用 code 换取手机号的完整链路，以及最实际的问题——这东西现在是按次收费的，怎么在业务里把它用得不心疼。适合正在做微信小程序登录模块的前端和后端，也适合用 uniapp 一份代码多端发布、需要给 App 和 H5 留兜底方案的同学。

1. 老方案为什么必须换掉：encryptedData 解密这条路的现实困境

1.1 两条链路的核心差异到底在哪

先把这个事情的来龙去脉说清楚。早期的手机号获取，本质上是一个"前端采集密文、后端拿钥匙解密"的模式：用户点击按钮后，微信在客户端把手机号用session_key加密，返回encryptedData和iv两个 Base64 字符串给前端，前端再原封不动传给自己的服务器，服务器得先通过wx.login拿到临时 code，换回openid和session_key，最后用session_key和iv对密文做 AES-128-CBC 解密。

这条链路最大的问题不是技术难度，而是它对"会话状态"的强依赖。session_key是一把钥匙，但它不由你的服务器掌控——用户换个设备登录、长时间不活跃、微信端刷新登录态，这把钥匙随时可能失效。一旦失效，解密就会抛出-41001或者-41003，而这个时候用户已经点过按钮了，你既没法复用那个encryptedData，也不能让用户再点一次，体验和排查成本都很高。

新的方案把这条链路彻底拆开了。同样是点击按钮，微信直接返回一个一次性的动态令牌code，你的服务器拿着这个code和自己的access_token去调微信的服务端接口，直接换回手机号明文。整个过程中，session_key这个中间态被彻底拿掉了，前端只需要负责把code递出去，后端只依赖自己的access_token——这是一个服务器完全可控的东西。

从表里能看出来，新方案不只是"更安全"，更关键的是可排查性变强了。老方案失败时你只能看到一句decrypt data fail，新方案失败时微信会明确告诉你40029 invalid code还是40001 invalid credential，这在实际运维里差别巨大。

1.2 什么情况下你还会碰到 encryptedData

这里要提醒一个容易被误解的点：新方案上线后，老方案并不是"立刻下线"，而是并行了一段时间。微信的过渡策略是按客户端基础库版本区分——基础库 2.21.2 及以上走code，更低版本仍然只返回encryptedData。

所以会出现一种情况：你在真机上调试，e.detail里code和encryptedData同时存在。这不是 bug，是微信为了兼容做的一段时间的双发。官方明确建议忽略encryptedData，只处理code。但如果你面对的是存量用户里还有一批老版本客户端（比如某些定制机、长期未更新的旧设备），稳妥的做法是在后端保留一条解密分支：

// 后端：兼容兜底逻辑（仅在 code 不存在时走解密） async function resolvePhone(detail, sessionKey) { if (detail.code) { // 新链路优先 return await exchangePhoneByCode(detail.code); } // 老链路兜底 if (detail.encryptedData && detail.iv && sessionKey) { return await decryptPhone(detail.encryptedData, detail.iv, sessionKey); } throw new Error('无法识别手机号获取回调，请检查基础库版本'); }

真正麻烦的不是写这段兜底，而是很多现成的登录 SDK（尤其是 uni-app 生态里一些封装好的uni-id版本）内部还在跑老逻辑，你直接在项目里引入，会遇到"明明后台已开通手机号服务，却总是解密失败"的诡异现象。判断方法很简单：翻一下 SDK 源码里有没有sessionKey相关的字段，有就是老实现，需要升级版本或者自己重写这一段。

还有一个特别隐蔽的坑，我第一次踩的时候排查了小半天：wx.login返回的code和getPhoneNumber返回的code，是两个完全不同的东西。前者是用来换openid/session_key的登录凭证，后者是手机号的动态令牌，两者名字一样，有效期都是 5 分钟，都可以用一次，但接口完全不通用。把登录 code 传给getuserphonenumber会直接返回40029；把手机号 code 传给jscode2session同样报40029。命令不认账，但错误码一样，很容易误判成"code 过期了"。

2. 前置条件没对齐，代码写对了也白搭

2.1 个人主体小程序在资质这一关就被拦住了

这个必须放在最前面说，因为它是硬性门槛：手机号快速验证组件只对非个人主体的小程序开放，并且需要完成微信认证。个人主体的小程序在后台根本找不到"手机号验证"这个功能入口，写再多代码也是白搭。

我在外包项目里见过好几次这样的沟通场景：客户拿着一个还没做认证的个人号让开发先做登录功能，开发吭哧吭哧写完，一测试直接失败，最后卡在商务环节。所以接到需求的第一件事，不是打开 IDE，而是确认三件事：小程序主体是不是企业/个体工商户、微信认证有没有过、后台"功能"菜单下面能不能看到"手机号验证"。这三条任何一条不满足，方案就要提前改道，别等到代码写完再返工。

2.2 手机号验证服务的开通与计费

手机号验证现在是按次计费的增值服务，需要在小程序后台 → 功能 → 手机号验证里主动开通，并且账号里要有余额。这一点和早期"免费随便调"的时代完全不同。

我不在这里写死单价，因为官方调整过几轮，而且快速验证和实时验证的报价不一定一样。你在后台这个页面里能看到当前的实时单价、剩余额度以及扣费明细，比任何博客里的数字都准。新开通的账号通常会给一定量的免费体验额度，用来跑通链路足够了。

有个细节值得留意：余额耗尽时，接口不会返回一个特别友好的提示。你可能会看到errcode从 0 变成别的值，或者干脆超时。所以上线前一定要在监控里给这个接口加告警，尤其是余额低于某个阈值时提前通知，否则线上用户点"一键登录"点不动，你的日志里只会留下一堆看不出原因的失败记录。

2.3 用户隐私保护指引：最容易被忽略、也最容易致命的一环

这是我见过翻车率最高的一步。微信要求小程序在调用涉及用户信息的接口前，必须在小程序后台 → 设置 → 服务内容声明 → 用户隐私保护指引里，明确声明收集"手机号"这项信息。没声明的后果不是警告，而是接口直接调用失败。

失败时的errMsg大致长这样：getPhoneNumber:fail api scope is not declared in the privacy agreement，或者另一个变体privacy permission is not authorized。新手看到这句往往会以为是代码问题，去翻文档翻半天，实际上后台补一条声明、等审核通过（通常几分钟到几小时），问题就没了。

除了后台声明，客户端侧还有一层"隐私弹窗"的交互要求。从 2023 年 9 月之后，微信引入了统一的隐私授权弹窗机制，你需要在合适的时机引导用户同意隐私协议。uniapp 里的处理方式大致是这样：

// uniapp 中处理隐私授权（放在小程序启动或首次需要用户信息时） // #ifdef MP-WEIXIN function ensurePrivacyAuthorized() { return new Promise((resolve, reject) => { if (typeof wx.getPrivacySetting !== 'function') { // 基础库过低，不需要处理隐私弹窗 return resolve(true); } wx.getPrivacySetting({ success: (res) => { if (res.needAuthorization) { // 需要弹出隐私协议，引导用户点击同意 // 实际项目中通常用一个自定义弹窗组件承载这段交互 reject({ needAuthorization: true, privacyContractName: res.privacyContractName }); } else { resolve(true); } }, fail: (err) => reject(err) }); }); } // #endif

这里的经验是：不要把隐私弹窗和获取手机号按钮做成同一个动作。用户点击"一键登录"时，理想流程是隐私弹窗先出现，用户点同意后，按钮的授权回调才继续走。如果两个弹窗叠在一起，用户很容易在慌乱中点到"拒绝"，而拒绝之后的手机号授权在同一个页面上是不太好重新触发的，只能引导用户去右上角设置里手动打开，转化率掉得很难看。

3. uniapp 端 getPhoneNumber 按钮的写法与事件细节

3.1 模板层：open-type 和事件名的书写规范

手机号授权没有对应的 JS API，只能靠<button>组件的open-type属性触发。这一点官方文档写得很清楚，但 uniapp 里的写法有几个容易写错的细节。

先看基础写法，Vue2 和 Vue3 语法在模板层基本一致：

<template> <view class="login-page"> <!-- 注意：必须是 button 元素，事件名全小写 --> <button class="phone-btn" open-type="getPhoneNumber" :loading="loading" :disabled="loading" @getphonenumber="handleGetPhoneNumber" > {{ loading ? '正在登录...' : '微信手机号一键登录' }} </button> </view> </template>

三个必须记住的点：

第一，open-type的值是getPhoneNumber，驼峰写法，这是属性值不是事件名，不能写成全小写。

第二，事件绑定统一用全小写的@getphonenumber。uniapp 在编译到小程序端时会把它转成bindgetphonenumber，如果你写成@getPhoneNumber这种驼峰形式，部分版本的编译器不会做转换，结果就是按钮点了没反应，而且控制台一片安静，连报错都没有。我见过至少三个项目栽在这上面。

第三，不能图省事用<view>加个@click来模拟。微信对这类敏感授权接口做的是"真实用户手势"校验，view上的点击事件拿不到授权回调，只会静默失败。

3.2 e.detail 里的字段结构，成功和失败都要看清

回调参数里e.detail的结构决定了你后端怎么写，值得单独拆开看：

// 授权成功的 e.detail { errMsg: 'getPhoneNumber:ok', code: 'e1a2b3c4d5e6f7...', // 手机号动态令牌，5 分钟有效且只能用一次 encryptedData: '...', // 老字段，官方建议忽略 iv: '...' // 老字段，官方建议忽略 } // 用户点击了"拒绝"的 e.detail { errMsg: 'getPhoneNumber:fail user deny' } // 后台未声明隐私协议时 { errMsg: 'getPhoneNumber:fail api scope is not declared in the privacy agreement' }

从这一组结构能直接读出处理策略：errMsg === 'getPhoneNumber:ok'且code存在，才继续往后走；user deny就弹一个温和的引导提示，告诉用户可以去右上角菜单里重新允许，不要用 alert 硬怼；剩下那些fail开头的，基本都是配置问题，直接打日志上报，别在前端猜。

const handleGetPhoneNumber = (e) => { const { errMsg, code } = e.detail || {}; if (errMsg !== 'getPhoneNumber:ok' || !code) { if (errMsg && errMsg.indexOf('user deny') > -1) { uni.showToast({ title: '你取消了手机号授权', icon: 'none' }); } else { uni.showToast({ title: '授权失败，请稍后重试', icon: 'none' }); // 上报异常，便于发现后台配置问题 console.error('[phone-auth] 授权失败', errMsg); } return; } // 只把 code 交给后端，前端不接触任何敏感数据 submitPhoneCode(code); };

这里有个很小的工程习惯，但在多端项目里很值：把submitPhoneCode单独抽成一个函数，不要在回调里直接写业务逻辑。因为 App 端和 H5 端拿不到这个 code（后面 6.2 会细说），你需要在这层做个平台分发，回调里保持干净会省很多事。

3.3 按钮样式与用户手势上的三个隐形坑

第一个坑是按钮的可用状态。:disabled="loading"这个写法看起来是好的防抖，但如果你的 loading 状态因为网络请求卡住而一直没复位，用户就会陷入"按钮点不动、页面也不报错"的死局。我的做法是给请求加超时兜底，无论成功失败都在finally里把 loading 置回 false，同时给按钮加一个 3 秒的自动解锁。

第二个坑是样式遮挡。很多项目为了好看，会把 button 用 CSS 改造成圆角卡片，常见做法是background: none; border: none;然后自己画。这本身没问题，但如果你用了pointer-events: none或者把一个透明遮罩层盖在按钮上面，事件就传不到 button 上了。判断方法很土但很有效：临时给 button 加个红色背景，看看点击区域到底在哪。

第三个坑是弹窗动画。有项目把手机号按钮放在一个自绘的授权弹窗里，弹窗有个 300ms 的缩放动画。用户在动画还没结束时快速点击，事件有时会丢失。这个属于交互细节，解决办法是在动画完成后再允许按钮可点击，或者干脆别把授权按钮放进需要动画的容器里。

4. 服务端用 code 换手机号：一条完整的链路

4.1 access_token 的集中管理与刷新策略

新链路的服务端只依赖一样东西：access_token。它是调用几乎所有微信服务端接口的通行证，默认有效期 7200 秒。这里有两个必须处理好的问题。

第一个问题是不要每次请求都去换 token。access_token的获取接口有每日调用次数限制，如果你每个用户登录都去拉一次，高峰期很容易把额度打满，然后全站接口一起报45009 reach max api daily quota limit。正确做法是把 token 缓存在 Redis 里，设置 7200 秒过期，并且提前 300 秒刷新，避免临界点上拿到一个马上失效的 token。

第二个问题是多服务实例的 token 互相顶掉。如果你的后端有多个进程或者多个服务都需要调微信接口，各自维护一份 token，就会出现"A 服务刚换的新 token，B 服务拿旧的去调，把 A 的顶掉了"这种经典问题。官方为此提供了稳定版接口，不占用普通 token 的调用配额，也不容易被互相覆盖：

// Node.js：使用稳定版接口获取 access_token const axios = require('axios'); async function fetchStableToken(appid, secret, forceRefresh = false) { const url = 'https://api.weixin.qq.com/cgi-bin/stable_token'; const { data } = await axios.post(url, { grant_type: 'client_credential', appid, secret, force_refresh: forceRefresh }); if (data.errcode) { throw new Error(`获取 access_token 失败: ${data.errcode} ${data.errmsg}`); } return data.access_token; } // 带缓存的取用封装 async function getAccessToken() { const cacheKey = `wx:token:${process.env.WX_APPID}`; const cached = await redis.get(cacheKey); if (cached) return cached; const token = await fetchStableToken(process.env.WX_APPID, process.env.WX_SECRET); // 提前 300 秒过期，留出刷新余量 await redis.set(cacheKey, token, 'EX', 7200 - 300); return token; }

还有一个安全习惯必须强调：AppSecret只能待在服务端环境变量里，绝对不能出现在小程序代码包或者前端请求参数中。access_token同理，它相当于你小程序的"万能钥匙"，泄露后别人可以以你的名义调各种接口。

4.2 调用 getuserphonenumber 换取手机号

拿到 token 之后，换取手机号就是一次很直接的 POST 请求：

// Node.js：用 code 换取手机号 async function exchangePhoneByCode(code) { const accessToken = await getAccessToken(); const url = `https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token=${accessToken}`; const { data } = await axios.post(url, { code }); if (data.errcode !== 0) { // 把错误码抛出去，交给上层做具体处理 const err = new Error(`换取手机号失败: ${data.errcode} ${data.errmsg}`); err.wxErrCode = data.errcode; throw err; } const info = data.phone_info; return { phoneNumber: info.phoneNumber, // 带区号的完整号码 purePhoneNumber: info.purePhoneNumber, // 纯号码，不带区号 countryCode: info.countryCode, // 国家码，如 86 watermarkAppId: info.watermark && info.watermark.appid }; }

返回值里有个watermark.appid，强烈建议做一次校验，确认它等于你自己的appid。这是防止令牌被跨应用滥用的最后一道防线，代码只有一行，但能在出现异常调用时第一时间发现。

实际返回的成功响应长这样，方便你对照调试：

{ "errcode": 0, "errmsg": "ok", "phone_info": { "phoneNumber": "13800000000", "purePhoneNumber": "13800000000", "countryCode": "86", "watermark": { "timestamp": 1700000000, "appid": "wx1234567890abcdef" } } }

4.3 错误码对照表与推荐的排查顺序

这个接口的错误码不多，但每一个都对应一个非常具体的配置或代码问题。我把它整理成一张表，建议贴在项目文档里：

排查的时候，我一般按这个顺序走，命中率最高：先看errMsg是不是配置类问题（隐私协议、未开通服务），再看errcode是不是 token 相关的，最后才怀疑前端传参。很多同学一上来就怀疑前端代码，翻半天发现是后台余额用完了，白白浪费时间。

另外要提醒一句：40029有一种很迷惑的场景——用户点击按钮后，页面因为网络慢卡了几秒，用户以为没反应就退出去重新进，两次点击产生的两个 code 都在路上，先到的那个成功了，后到的那个自然就40029。所以后端对同一个用户的并发请求做一次幂等合并，是很有必要的。

5. 实时验证组件：什么时候值得多花那次短信

5.1 快速验证和实时验证的选型依据

微信其实提供了两个手机号组件，名字很像，适用场景差别不小。

手机号快速验证组件就是前面讲的getPhoneNumber。它拿到的是用户在微信里绑定的那个号码，整个过程没有短信，速度极快，用户点一下就行，转化率最高。它的局限在于：这个号码是"微信认为属于这个用户的号码"，但不代表它此刻一定在用户手上。用户换了号没更新微信绑定、号码是家里人的副卡、号码已经停机但没解绑，这些情况下快速验证拿到的号码可能是失效的。

手机号实时验证组件会走一次短信验证码流程：用户点击后输入收到的验证码，验证通过才返回结果。因为多了一次真实验证，号码的"实时有效性"是有保证的。

选型逻辑其实很简单：只要业务对"这个号码现在能不能收到短信/电话"有要求，就上实时验证；只是需要一个账号标识和联系方式，快速验证就够了。我经手的一个项目同时用了两个：主登录流程走快速验证，提现前的大额操作走实时验证，成本和体验都平衡得不错。

5.2 接入差异其实只有两处

好消息是，实时验证的接入改动非常小，和快速验证共用同一个换取接口。

<!-- 实时验证组件 --> <button class="phone-btn" open-type="getRealtimePhoneNumber" @getrealtimephonenumber="handleRealtimePhone" > 短信验证并绑定手机号 </button>

const handleRealtimePhone = (e) => { const { errMsg, code } = e.detail || {}; if (errMsg !== 'getRealtimePhoneNumber:ok' || !code) { uni.showToast({ title: '验证未完成', icon: 'none' }); return; } // 注意：换取的接口和快速验证完全一样 submitPhoneCode(code); };

注意两点：事件名从getphonenumber变成了getrealtimephonenumber，成功时的errMsg前缀也跟着变，判断成功的时候别硬编码写死getPhoneNumber:ok，否则实时验证那条路会一直判成失败。另外，拿到的code依然走/wxa/business/getuserphonenumber这个接口，后端代码一行都不用改，只是计费口径不同。

顺便说一个我在实际项目里发现的现象：实时验证的短信到达率在不同运营商和不同时段会有波动。如果用户点了按钮但十分钟没收到短信，他的第一反应是反复点，这时候前端必须做节流，同一用户 60 秒内只能触发一次，否则用户以为没发出去，实际上后台已经扣了好几次费用。

6. 成本控制与工程化落地：别让一次点击变成一笔账

6.1 去重、缓存与幂等：把每一次计费都花在刀刃上

既然每次调用都计费，那"怎么少调"就是工程问题。我一般在项目里落三层防护。

第一层是数据库层面的唯一约束。用openid做主键或者唯一索引，存一条openid → phone的映射。用户第二次进来登录时，先查这张表，命中就直接签发登录态，根本不触发前端授权按钮。这一层能省掉绝大部分重复调用，因为真实业务里用户登录是高频动作，但手机号绑定只需要一次。

第二层是前端防抖加按钮置灰。前面提过，用户在网络慢的时候容易重复点。除了disabled，我还会加一个本地的请求锁：

let submitting = false; async function submitPhoneCode(code) { if (submitting) return; submitting = true; try { const res = await uni.request({ url: `${BASE_URL}/api/auth/phone`, method: 'POST', data: { code }, timeout: 8000 }); // 处理登录成功逻辑 } finally { // 无论成败都要解锁，避免用户永远点不动 submitting = false; } }

第三层是服务端的幂等键。用openid + 手机号组合成幂等键写进 Redis，有效期设个 60 秒。同一用户带着两个不同code打过来时，第二次直接返回第一次的结果，不再向微信发起请求。这一层是应对并发重复请求的最后一道闸。

6.2 条件编译：一份代码怎么照顾 App 和 H5

用 uniapp 最大的诱惑就是一套代码多端跑，但手机号这个功能是小程序独有的，App 和 H5 上open-type完全不起作用。合理的做法是在组件层用条件编译，把三个平台的入口分开，但向上层暴露同一个回调。

<template> <view class="auth-entry"> <!-- #ifdef MP-WEIXIN --> <button class="phone-btn" open-type="getPhoneNumber" @getphonenumber="handleGetPhoneNumber" >微信一键登录</button> <!-- #endif --> <!-- #ifdef APP-PLUS || H5 --> <button class="phone-btn" @click="goSmsLogin">手机号验证码登录</button> <!-- #endif --> </view> </template>

这样组织的好处是：业务层只关心"拿到手机号"这个结果，至于这个号码是微信给的还是短信验证来的，通过一个统一的onPhoneResolved(phone)回调消化掉。App 端走自己的短信服务，H5 端也走短信，只不过各自对接的短信通道不同，和小程序这条链路完全解耦。

顺带提一句manifest.json里的配置。小程序的appid是在mp-weixin节点下配置的，如果这里填错了，或者填的是测试号，手机号接口是调不通的——测试号不支持这个能力。还有一个细节，mp-weixin节点下可以设置最低基础库版本，这个值会影响你能否使用新链路，最低建议设到 2.21.2 以上。

6.3 上线前的自检清单

这个清单是我从一个项目复盘里留下来的，每次上线前照着过一遍，能挡掉九成以上的低级事故：

• 小程序主体是非个人主体，且微信认证已通过
• 后台"功能 → 手机号验证"已开通，账号余额充足，并已配置低余额告警
• 用户隐私保护指引中已声明收集"手机号"，且审核已通过
• 前端按钮是原生button，事件名为全小写的@getphonenumber
• 前端不做code的任何持久化存储，只在内存里传给后端
• 后端access_token走缓存，提前 300 秒刷新，多实例共用同一份
• 后端校验watermark.appid是否等于自身appid
• openid → phone映射表有唯一索引，登录优先查表而不是先授权
• 接口级限流已配置，单用户 60 秒内最多触发一次
• 错误码分类处理，40029和40001有独立的日志与告警

我在实际项目里踩过一次比较典型的坑：隐私协议审核通过后，我们只在开发环境测了，测试环境用的还是老版本的后台配置，结果灰度发布时测试环境的用户全部授权失败。那之后我就养成了一个习惯——把这个自检清单拆成开发环境、测试环境、生产环境三份，每个环境单独过一遍，因为小程序后台的配置是跟着 appid 走的，不同环境用不同 appid 就等于三套配置。

最后分享一个我觉得挺实用的小技巧。手机号授权失败的原因里，配置类问题占了绝大多数，但前端拿到的errMsg是英文的、也挺长，用户看不懂，开发者看日志又容易漏。我的做法是在前端捕获失败后，把errMsg一起打点上报，同时在后端维护一张"错误码 → 处置建议"的映射表，运维同学看到告警时能直接知道是该去补隐私声明，还是该去充值。这个映射表不需要多复杂，十几行配置，但能把平均故障恢复时间从小时级压到分钟级。