上周帮一个朋友查一键登录的问题场景非常典型真机上用 HBuilderX 跑得好好的云打包之后用户一直反馈点登录没反应控制台打出来一行uni-app network: unavailable。我远程看了半小时最后问题不在网络而是云函数里没有正确拿到access_token服务端返回了undefined。这种玄学报错其实一点也不玄一次登录点击涉及前端 SDK、云函数、运营商网关三端配合任何一环断掉都会表现成网络不可用。这篇文章我就按自己的实操顺序把 uni-app 一键登录从云函数配置到前端调用的完整链路讲清楚。如果你也准备在 App 里集成一键登录或者已经集成了但总在真机联调时翻车这篇应该能帮你少走不少弯路。1. 一键登录的完整信任链点击、换取、绑定1.1 一次点击背后其实有两个步骤很多人容易把一键登录理解成一个单独的 SDK 方法点了以后手机号就直接返回给前端。实际上不是这样。以 uni-app App 端的 univerify 方案为例完整链路是前端通过uni.login({ provider: univerify })调起运营商网关的取号能力。运营商返回的并不是手机号明文而是一个临时凭证一般包含openid和access_token。前端把这个凭证传给云函数。云函数拿着凭证去 uniCloud 的服务端换取手机号并完成注册或登录。云函数返回用户 token 和用户信息前端把 token 存起来登录成功。注意第 2 步到第 4 步之间前端从来没有拿到过手机号明文。这是关键也是很多教程没讲透的地方。很多人以为一键登录就是前端直接拿手机号然后调一个登录接口这种理解会导致你在设计云函数接口时把手机号当成参数传来传去既不安全也容易被第三方抓包。1.2 为什么要先拿临时凭证而不是直接把手机号给前端你可以把access_token想象成一张临时入场券。持有这张券的人可以去柜台换一份完整的用户信息但券本身不包含手机号。这样做的好处是手机号不会出现在前端网络请求里减少泄露风险。凭证有过期时间即使被截获攻击者也不能长期使用。后续换号、绑定手机号等操作都可以基于服务端返回的openid来做而不是依赖用户手动输入。如果你在社区里看到有人说一键登录拿不到手机号大概率就是把第 2 步返回的authResult当成了最终结果没有继续走云函数换号逻辑。1.3 一键登录和短信验证码怎么选短信验证码的优点是通用几乎任何端都能用但成本高、体验差。一键登录的优点是无感、转化率高尤其适合老用户回流但也有自己的限制只适合 App 端Web 端没办法用。需要走运营商网关某些设备、某些网络环境下会失败。需要提前在 DCloud 开发者中心和 uniCloud 控制台完成配置。首次使用需要用户同意隐私协议否则要考虑降级到短信验证码。我的建议是一键登录作为首选项短信验证码作为兜底。不要把一键登录做成唯一的登录方式不然用户在 Wi-Fi 环境或者不支持网关取号的机型上会直接被卡死。2. 云函数侧配置先让服务认你的 App2.1 开通并绑定 uniCloud 服务空间一键登录的服务端逻辑依赖 uniCloud所以第一步不是写代码而是先有一个云服务空间。在 HBuilderX 里操作还是比较顺的打开项目确认存在uniCloud目录没有就新建一个。在uniCloud/cloudfunctions目录上右键选择创建云服务空间。按项目所属环境选择阿里云或腾讯云创建完成后在manifest.json里关联这个服务空间。确认manifest.json里已经填写了真实有效的 AppID也就是__UNI__开头的那个。这里有个容易踩的坑很多人本地有一个服务空间打包时用的却是另一个服务空间结果真机调试时能登录线上包云函数根本查不到表。建议从开发第一天就把开发版服务空间和正式版服务空间区分开并且把环境变量配好不要等到上线前临时抱佛脚。2.2 在 DCloud 开发者中心开启 univerify 服务服务空间创建好之后需要去 DCloud 开发者中心把一键登录服务打开。路径大概是开发者中心 - select App - 一键登录 - 开通服务开通后系统会要求你填写 App 的包名、签名等信息。这一步很多人会忽略直接点了开通结果后面真机调 one-click 登录时返回应用未授权。所以开通服务后务必确认三件事App 的包名和 Android 包名一致。iOS 的 Bundle ID 配置正确。如果是 Android签名信息要用正式打包时的那把签名证书而不是调试用的默认签名。这些信息一旦不对线上用户一登录就废。2.3 云函数目录结构与 uni-id 依赖安装我习惯的做法是不直接写一个从零开始的云函数而是基于 uni-id 公共模块来做。因为 uni-id 已经把用户表、token、密码加密、登录态这些都封装好了我们只需要在云函数里调用它的方法。目录结构大概是这样uniCloud └── cloudfunctions └── login-by-univerify ├── index.js └── package.json在 HBuilderX 里右键login-by-univerify目录选择从插件市场导入 uni-id 公共模块或者在package.json里声明依赖{ name: login-by-univerify, version: 1.0.0, main: index.js, dependencies: { uni-id: 3.3.27 } }uni-id 的版本不同方法名和使用方式会有差异。老版本里常见的是uniID.loginByUniverify新版本中 uni-id-pages 方案可能已经封装到uni-id-cf云函数里。实际以你安装的版本为准但原理都一样。2.4 云函数代码怎么写得不容易出错以一个基本的云函数为例use strict const uniID require(uni-id) exports.main async (event) { // 前端 uni.login 返回的临时凭证 const { openid, access_token } event // uni-id 内部会调用 uniCloud 服务端接口用临时凭证换取手机号 const res await uniID.loginByUniverify({ openid, access_token }) // res.code 0 表示登录成功 return res }这段代码看起来简单但有几个容易忽略的地方第一event里的字段名不能拼错。前端传access_token你非要用accessToken云函数接收后就是undefined后面换号必然失败。我在排查network: unavailable时就遇到过这种低级问题。第二uni-id依赖用户表。如果登录用户第一次进来uni-id 会自动创建一条用户记录默认密码为空后续你可以引导用户设置密码或绑定其他登录方式。第三云函数上传要带上公共模块。HBuilderX 里右键云函数目录时选择上传所有公共模块否则线上运行时找不到uni-id。你需要在 uni-id 的配置里确认几个关键项{ passwordSecret: 你自己生成的长随机字符串, tokenSecret: 另一个长随机字符串, tokenExpiresIn: 7200, tokenExpiresThreshold: 3600, tokenEncrypter: aes-256-gcm }tokenExpiresIn建议不要设置太长。移动端登录态一般 7 天比较合理但如果你是做金融、政务类 App建议按天甚至按小时缩短。3. 前端调用登录按钮背后那几行关键代码3.1 manifest 里要勾选 OAuth 模块前端不是写一段uni.login就完事了还要确保原生层集成了 univerify SDK。在manifest.json的 App 模块配置里把 OAuth 模块选中并确认里面包含 univerify。如果用的是 HBuilderX 的标准基座一般已经内置了 univerify。但如果做了自定义调试基座就要重新勾选并打包基座否则真机调uni.login会直接报 provider 不存在。另外iOS 端如果开了 ATS 限制建议确认接口请求地址是 HTTPS。uniCloud 默认走 HTTPS一般不会有问题但如果你自己写了转发接口就另说了。3.2 调起 univerify 并拿到临时凭证下面是调用端比较完整的流程代码function loginByUniverify() { return new Promise((resolve, reject) { uni.login({ provider: univerify, univerifyStyle: { autoBack: false, titleText: 一键登录, buttonText: 本机号码登录, privacyText: 登录即代表同意《用户协议》和《隐私政策》, protocol: [ { name: 用户协议, url: https://your-domain.com/protocol }, { name: 隐私政策, url: https://your-domain.com/privacy } ] }, success: async (res) { if (!res.authResult) { reject(new Error(authResult为空请检查服务是否开通)) return } const { openid, access_token } res.authResult try { const { result } await uniCloud.callFunction({ name: login-by-univerify, data: { openid, access_token } }) if (result.code 0) { resolve(result) } else { reject(new Error(result.message || 登录失败)) } } catch (e) { reject(e) } }, fail: (err) { reject(err) } }) }) }这里面的事件命名、字段名在不同版本的 uni-app SDK 里可能有细微差别。如果你运行之后发现res.authResult是undefined可以打印完整res看一下确认是否改成了res.result或res.userInfo。不要想当然。3.3 登录成功后的用户态处理云函数返回成功后需要把 token 和用户信息存到本地。我这里通常会把用户信息做最小化缓存async function handleUniverifyLogin() { try { const res await loginByUniverify() uni.setStorageSync(uni_id_token, res.token) uni.setStorageSync(uni_id_user_info, res.userInfo) // 如果是新用户可以根据 res.isNewUser 判断是否跳资料完善页 if (res.isNewUser) { uni.navigateTo({ url: /pages/profile/complete }) } else { uni.navigateBack() } } catch (e) { // 用户取消、网络异常、云函数异常都走这里 uni.showToast({ title: e.message || 登录失败请重试, icon: none }) } }注意云函数返回的userInfo里如果包含手机号前端展示时不要直接明文存到本地。尽量只存id、nickname、avatar这类非敏感字段手机号只在需要展示时从服务端获取或者做脱敏处理。4. 真机调试常见故障从 network: unavailable 到电话权限4.1 为什么经常出现 network: unavailableuni-app network: unavailable是 uni-app 项目里一个很容易让人误判的报错尤其是调 uniCloud 云函数时。它并不一定代表手机没有网络更多时候是前端 SDK 在调用 uniCloud 网关时失败了。我整理了一下自己遇到过的几种场景现象常见原因处理办法真机每次点登录都报 unavailable自定义基座没重新打包重新打自定义基座确认包含 univerify 模块开发环境正常线上包才报错服务空间配置不对检查 manifest 关联的服务空间是否和云函数部署的一致换了一台手机就报错运营商网关无法取号降级到短信验证码或引导用户切换网络小程序、Web 端报这个错uniCloud 域名未配置根据平台要求在后台配置 request 合法域名调用云函数报网络错误云函数运行超时打开云函数性能分析检查是不是 uni-id 公共模块没上传如果确认云函数日志里有请求进来但前端报 unavailable那多半是返回数据格式问题或者云函数超时。千万不要一上来就怀疑手机断网。4.2 一键登录到底需不需要电话权限这个问题在社区里被反复问。我的判断是univerify 一键登录本身不强制要求申请READ_PHONE_STATE权限也不应该在你的登录页里主动去申请电话权限。原因很简单一键登录走的是运营商网关的取号能力SDK 在调起网关页面时已经完成了授权不需要前端拿到电话权限。如果你在登录页弹了个权限框要读取手机状态和身份用户大概率会拒绝拒绝之后反而影响后续流程。那什么时候需要关注电话权限如果你的 App 里还有其他功能真的需要读取设备状态比如设备指纹、SIM 卡识别等这些权限请求要在登录流程之外单独处理。不要为了一个登录按钮把敏感权限和默认授权绑在一起隐私合规上很容易出问题。另外iOS 端不存在电话权限弹窗问题但你需要在隐私说明里写明本应用使用一键登录功能会经过用户授权后获取手机号码用于登录和账户安全验证。4.3 调试基座、自定义基座和正式包的差异开发阶段用 HBuilderX 内置标准基座能跑通uni.login不代表正式包也能跑通。标准基座用的是 DCloud 测试包名和测试签名一键登录服务授权是 DCloud 自己的配置而不是你的项目配置。所以当你切换到自定义调试基座或者正式云打包之后包名、签名会变成你自己的如果开发者中心里没有把你正式签名的 SHA1 指纹和包名信息配好就会出现标准基座能登录自定义基座不能登录的诡异现象。这个问题我碰到过不止一次。排查方式也很直接先看前端uni.login的 fail 回调返回的错误码。再去 DCloud 开发者中心核对包名和签名。最后才考虑是不是云函数的问题。把顺序倒过来会浪费大量时间。5. 上线前最容易翻车的三个环节包名、证书和加固重签5.1 包名与签名是一键登录的身份证明一键登录不是你在代码里传了appid就能跑通的。Android 端运营商网关会校验请求来源的包名和签名证书iOS 端会校验 Bundle ID 和对应的签名配置。也就是说即使你的 App 功能全部正常只要包名或签名和一个登录服务配置不一致线上用户点一键登录就会失败而且失败原因往往很模糊。我给团队定的规矩是项目启动前就把 Android 包名、iOS Bundle ID 记录下来每换一次签名证书立刻更新到开发者中心上线前检查一遍正式包里的包名和签名是否与后台完全一致。检查签名信息可以用命令keytool -printcert -jarfile your-app.apk看到SHA1和SHA256之后再去后台对比经常能找到问题。5.2 加固后重新签名的正确姿势很多 App 上线前会做加固比如 360 加固、腾讯乐固、梆梆加固等。加固本身不会破坏签名问题出在加固后的重新签名环节。如果你拿到的加固包是签名过的重新用另一个 keystore 签名或者干脆用了 debug 签名那 Android 包名虽然没变但签名指纹已经变了一键登录立刻就废。更严重的是微信登录、支付宝支付、地图定位这些第三方 SDK 也会一起出问题。正确操作流程是用正式 keystore 打包出未加固的原包。用加固工具加固。加固完成后用同一个正式 keystore 重新签名。用apksigner验证签名信息是否一致。签名命令大概是这样zipalign -v 4 app-protected.apk app-aligned.apk apksigner sign --ks release.jks --ks-key-alias your_alias --out app-signed.apk app-aligned.apk apksigner verify -v app-signed.apk注意这里有一个容易踩的坑很多加固工具会生成一个默认签名包如果你不仔细看直接把那个默认签名的包上传到市场后面就等着被用户投诉登录不了吧。5.3 远程升级时不要偷偷改证书如果你用了 uni-app 的远程升级方案或者任何热更新/整包升级方案都要特别注意正式版的证书和包名一旦发布就不要轻易换。即使你觉得换证书是为了更安全对一键登录来说这就是身份变更。之前有个项目运营同学换了公司主体顺带把 Android 签名改成新公司的证书结果一键登录、微信登录全部失效。最后临时发版把签名改回来才恢复。所以如果你一定要换签名证书请至少提前一周在开发者中心和后台做好迁移并且准备短信验证码兜底。千万不要在发版前一天才改。6. 再补充几个选型与合规建议6.1 Wi-Fi 环境下的降级策略一键登录依赖运营商网关取号理论上最好在蜂窝网络环境下走。Wi-Fi 环境下有些设备也能取号成功但并不是所有运营商、所有 App 都支持。我建议在 UI 上不要把一键登录按钮做成唯一的入口。当用户点击后如果 5 秒内没有回调成功自动弹出一个切换到短信验证码的按钮避免把人卡死在登录页。6.2 隐私合规手机号属于敏感个人信息一键登录最大的风险不在技术在合规。手机号是敏感个人信息必须在用户点击登录前展示清晰的隐私政策并且用户主动授权后才可以调用uni.login。实际项目里建议这么做登录页首次加载就展示《用户协议》和《隐私政策》。用户勾选同意后才能点一键登录按钮。不要把同意协议和登录按钮混在一起做个默认同意。在隐私政策里单独写清楚一键登录会收集哪些信息、用来做什么、会不会共享给第三方。合规这件事不是给审核看的是为了防止线上线下都能出大问题。很多应用市场现在对隐私权限要求非常严格一键登录如果处理不当轻则下架重则被投诉。6.3 什么时候建议放弃一键登录如果你做的是企业内部工具、低频后台类 App用户量不大我不建议专门为了一键登录去维护一套云函数和签名体系。短信验证码或者账号密码登录已经够用。反过来如果你做的是电商、社区、工具类 App用户大部分场景是手机使用那可以认真考虑一键登录。首次登录的流畅度直接决定转化率一个不需要输入验证码的登录体验确实能让用户留存好不少。我在实际项目里的习惯是一键登录 短信验证码双入口一键登录失败时静默降级短信验证码永远作为保底项。这样既保证了主流程体验也不会因为某个机型取号失败而彻底堵死用户。别把一键登录当成银弹。