更新记录

1.0.0（2026-11-05）

• 新增 Android Credential Manager 与 iOS GoogleSignIn 官方原生身份登录实现，支持 ID Token 与 nonce；实际平台验收边界见 README。
• 新增本地环境检查，按凭据组件所需最低 Google Play 服务版本检测 Android 可用性。
• 新增本地退出、按请求编号取消登录等待、可配置超时、并发保护与单次回调。
• 新增原生与 UTS 脱敏诊断、完整报告一键复制、固定快照分段及复制失败手动回退。
• 新增 uni-app Vue2/Vue3 与 uni-app x 分类示例，按登录、会话、测试和配置 tabs 展示全部公开能力，保留公共状态与完整日志。
• 新增真实接口空 ID、无效时限和无请求取消测试入口，以及开发者 OAuth 配置、后端验签与多端验收说明。

平台兼容性

uni-app(5.33)

uni-app x(5.33)

Google 授权登录 UTS 插件

介绍

lizhao-google-login 面向 uni-app、uni-app x，封装 Google 官方原生身份登录，在 Android、iOS 取得 ID Token，由业务后端验签后建立自己的账号会话。提供登录、本地退出、取消超时、环境检查和脱敏诊断。当前作为开发者接入与自测源码交付；真实 OAuth 登录、后端验签及 iOS Apple 编译/真机回跳仍需在自己的应用中验收，不能把本地编译或参数测试视为登录成功。

功能特色

适合哪些场景

本插件只处理身份认证，不提供 accessToken、refreshToken、serverAuthCode、额外 scopes、Google 撤权或业务后端登录接口。访问 Drive、Calendar 等 API 需另行实现对应授权；无需为了使用本插件额外接入 Firebase 或 uniCloud。

下载与导入

从基础到进阶：按业务模块使用

基础功能配置示例

接入前准备

Google Cloud 后台由项目管理者操作；若 Google 要求账号安全验证，需该账号本人完成。Client ID 是公开应用标识，Client Secret 是服务端秘密，插件不接收 Secret，不应将密码、证书私钥或 Token 写入前端配置。

插件按每次调用配置，无需额外的初始化 API。下面的 UTS 函数可放在 uni-app x 页面脚本中，由登录按钮传入页面中填写的真实 Web Client ID；省略 nonce、iosClientId 和 timeoutMs 时分别采用未设置、读取 iOS Bundle 配置、120000 毫秒。iOS 仍须完成下文的 Bundle 配置。

import { signInGoogle, GoogleSignInOptions } from '@/uni_modules/lizhao-google-login'

function requestGoogleLogin(webClientId: string): string {
  const options: GoogleSignInOptions = {
    serverClientId: webClientId,
    success: (result) => {
      // result.idToken 通过 HTTPS 交给自己的业务后端；不打印、保存或复制令牌。
      console.log('已取得 Google 凭据，等待后端验签；请求=' + result.requestId)
    },
    fail: (error) => { console.log('Google 登录失败：' + error.errCode.toString() + '；' + error.errMsg) },
    complete: (result) => { console.log('完成回调：' + result.errCode.toString()) }
  }
  return signInGoogle(options)
}

注册示例页面

在各自宿主的 pages.json 的 pages 数组中加入对应对象，保留其他页面。uni-app x 使用：

{
  "path": "uni_modules/lizhao-google-login/example/uniappx/index",
  "style": { "navigationBarTitleText": "Google授权登录" }
}

uni-app 的 Vue2 / Vue3 使用：

{
  "path": "uni_modules/lizhao-google-login/example/uniapp/index",
  "style": { "navigationBarTitleText": "Google授权登录" }
}

iOS 配置代码

将下面片段合并到 uni_modules/lizhao-google-login/utssdk/app-ios/Info.plist 已有的 <dict> 中，替换所有 YOUR_... 为自己项目的真实值。保留宿主原有的其他 URL Scheme；示例字符串不能直接用于登录。Android 不需要这些字段。

<key>GIDClientID</key>
<string>YOUR_IOS_CLIENT_ID.apps.googleusercontent.com</string>
<key>GIDServerClientID</key>
<string>YOUR_WEB_CLIENT_ID.apps.googleusercontent.com</string>
<key>CFBundleURLTypes</key>
<array><dict><key>CFBundleURLSchemes</key><array>
  <string>com.googleusercontent.apps.YOUR_IOS_CLIENT_ID</string>
</array></dict></array>

反转 Scheme 使用 Google 控制台提供的 iOS URL Scheme；不要反转 Web ID。调用时传入的 iosClientId 与 Bundle 中 GIDClientID 同时存在时须一致；serverClientId 与 GIDServerClientID 同时存在时也须一致。配置变更后重新构建 iOS 原生包。参考 Google iOS 配置指南。

高级示例

组合配置与精确取消

以下 UTS 示例适用于 uni-app x。webClientId 来自自己的 Web 客户端，iosClientId 在 Android 传空字符串、在 iOS 可传真实 ID 或留空读取 Bundle，challenge 来自自己的后端。页面调用 loginWithChallenge；关闭页面或点击取消时调用 cancelOwnLogin。业务先限制一次原生操作，插件也会拒绝冲突请求。

import { signInGoogle, cancelGoogleLogin, GoogleSignInOptions } from '@/uni_modules/lizhao-google-login'
let loginRequestId = ''

function loginWithChallenge(webClientId: string, iosClientId: string, challenge: string) {
  if (loginRequestId.length > 0) return
  const options: GoogleSignInOptions = {
    serverClientId: webClientId,
    iosClientId: iosClientId,
    nonce: challenge,
    timeoutMs: 30000,
    success: (result) => { console.log('已取得凭据，请交后端核对挑战；请求=' + result.requestId) },
    fail: (error) => { console.log('授权结果：' + error.errCode.toString() + '；' + error.errMsg) },
    complete: (result) => { if (loginRequestId == result.requestId) loginRequestId = '' }
  }
  loginRequestId = signInGoogle(options)
}

function cancelOwnLogin() {
  if (loginRequestId.length == 0) return
  const result = cancelGoogleLogin(loginRequestId)
  console.log('本地等待已取消=' + result.cancelled.toString() + '；系统界面可能保留=' + result.nativeUiMayRemain.toString())
}

环境检查、退出与诊断

以下 UTS 函数可直接放入页面脚本。环境检查不用登录账号，也不代表后台登记验证通过。inspectGoogle 传入实际配置或空字符串查看缺失项；logoutGoogle 由“本地退出”按钮调用；诊断函数由各自按钮触发，不自动上传。

import { checkGoogleLoginEnvironment, signOutGoogle, getGoogleLoginDiagnosticsSync, clearGoogleLoginDiagnosticsSync } from '@/uni_modules/lizhao-google-login'

function inspectGoogle(webClientId: string, iosClientId: string) {
  checkGoogleLoginEnvironment({
    serverClientId: webClientId,
    iosClientId: iosClientId,
    success: (result) => { console.log('本地可用=' + result.available.toString() + '；' + result.checks.join('；')) },
    fail: (error) => { console.log('环境检查失败：' + error.errCode.toString()) },
    complete: (result) => { console.log('环境检查完成：' + result.errCode.toString()) }
  })
}
function logoutGoogle() {
  signOutGoogle({
    timeoutMs: 30000,
    success: (result) => { console.log('本地退出完成；业务后端会话请另行退出') },
    fail: (error) => { console.log('退出失败：' + error.errCode.toString() + '；' + error.errMsg) },
    complete: (result) => { console.log('退出完成回调：' + result.errCode.toString()) }
  })
}
function readGoogleDiagnostics() {
  const result = getGoogleLoginDiagnosticsSync()
  console.log('插件=' + result.pluginId + '；公共日志=' + result.logs.length.toString() + '；丢弃=' + result.droppedLogs.toString())
}
function clearGoogleDiagnostics() {
  clearGoogleLoginDiagnosticsSync()
  console.log('插件诊断已清理，账号状态不变')
}

后端通过可信库验证 Google ID Token 的签名、iss、aud、exp，再用验签后的 sub 关联用户；设置 nonce 时还要验证挑战。客户端解码 JWT 或拿到一个非空字符串都不等于建立可信业务会话。参考 Google 后端验签指南。

完整示例

页面分类与功能入口

交付示例统一使用紧凑业务 tabs。默认显示“登录”，选中态清晰；切换只改变展示，保留配置、请求、忙碌状态和已有日志，不重新调用 SDK。状态与诊断放公共区域，错误不会因切换分类而消失。示例的“测试”页同时给出填写配置、检查环境、登录或取消、本地退出的操作顺序；六个公开 API 均可从分类或公共区域触发。

完整分类页面路径：uni-app x 为 uni_modules/lizhao-google-login/example/uniappx/index.uvue；uni-app 为 uni_modules/lizhao-google-login/example/uniapp/index.vue。页面模板主源是 uni_modules/lizhao-google-login/example/page.template；保留脚本、回调与完整报告合同，两宿主仅语法和滚动适配不同。

下面分别给出两种宿主可复制的完整最小页面，串联输入、忙碌保护、成功/失败/完成和卸载取消。它们不包含示例页面的全部样式与报告实现；需要全部功能时直接注册上述真实分类页面。

uni-app x 完整最小页面

页面输入实际 Web Client ID；iOS Client ID 从已配置 Bundle 读取。

<template>
  <view style="padding:12px">
    <input v-model="clientId" placeholder="Web Client ID" />
    <button :disabled="busy" @click="login">使用 Google 账号登录</button>
    <text>{{ status }}</text>
  </view>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import { signInGoogle, cancelGoogleLogin, GoogleSignInOptions } from '@/uni_modules/lizhao-google-login'
const clientId = ref('')
const status = ref('尚未登录')
const busy = ref(false)
let requestId = ''
function login() {
  if (busy.value) return
  busy.value = true
  const options: GoogleSignInOptions = {
    serverClientId: clientId.value,
    timeoutMs: 120000,
    success: (result) => {
      // 将result.idToken通过HTTPS交业务后端验签；这里仅显示存在性，不打印或保存令牌。
      status.value = '已取得身份凭据，等待后端验签'
    },
    fail: (error) => { status.value = error.errCode.toString() + '：' + error.errMsg },
    complete: (result) => {
      if (requestId != result.requestId) return
      requestId = ''
      busy.value = false
    }
  }
  requestId = signInGoogle(options)
}
onUnload(() => { if (requestId.length > 0) cancelGoogleLogin(requestId) })
</script>

uni-app Vue2 / Vue3 完整最小页面

通用 Options API，带环境检查、登录、本地退出与卸载取消。

<template>
  <view>
    <input v-model="clientId" placeholder="Web Client ID" />
    <button @click="inspect">检查环境</button>
    <button :disabled="busy" @click="login">使用 Google 账号登录</button>
    <button :disabled="busy" @click="logout">本地退出</button>
    <text>{{ status }}</text>
  </view>
</template>
<script>
import { checkGoogleLoginEnvironment, signInGoogle, signOutGoogle, cancelGoogleLogin } from '@/uni_modules/lizhao-google-login'
export default {
  data() { return { clientId: '', status: '尚未登录', requestId: '', busy: false } },
  onUnload() { if (this.requestId) cancelGoogleLogin(this.requestId) },
  methods: {
    inspect() {
      checkGoogleLoginEnvironment({ serverClientId: this.clientId,
        success: result => { this.status = result.available ? '本地条件满足' : result.checks.join('；') },
        fail: error => { this.status = error.errCode + '：' + error.errMsg }
      })
    },
    login() {
      if (this.busy) return
      this.busy = true
      this.requestId = signInGoogle({ serverClientId: this.clientId,
        success: result => { this.status = '已取得ID Token，等待业务后端验签' },
        fail: error => { this.status = error.errCode + '：' + error.errMsg },
        complete: result => {
          if (this.requestId !== result.requestId) return
          this.requestId = ''
          this.busy = false
        }
      })
    },
    logout() {
      if (this.busy) return
      this.busy = true
      this.requestId = signOutGoogle({ success: result => { this.status = '本地退出完成，业务会话需后端另行退出' },
        fail: error => { this.status = error.errCode + '：' + error.errMsg },
        complete: result => {
          if (this.requestId !== result.requestId) return
          this.requestId = ''
          this.busy = false
        }
      })
    }
  }
}
</script>

开发者验收清单

两端示例底部可复制的报告包含运行环境、插件和原生构建来源、脱敏结果/异常及本页保留的完整日志，页面只显示最近摘要。uni_modules/lizhao-google-login/example/report.uts 为报告主源，uni_modules/lizhao-google-login/static/report.js 是同源生成的传统宿主模块。页面报告缓存上限 1000 条 / 1MiB UTF-8，截断会记录丢弃数量与范围。未知 HX 编译版本、基座身份等明确标记 unknown；不以排查电脑的版本代替安装包构建来源。分段使用同一固定快照，复制失败保留原段并提供手动复制，复制不清空日志。

API 用途速查

登录、环境与退出参数

checkGoogleLoginEnvironment只接收clientId相关字段及回调；signOutGoogle只接收timeoutMs及回调。callback缺省时仍执行真实操作和诊断；建议至少提供fail与complete。所有业务回调异步派发，返回请求编号后才交付；同一次success与fail互斥，complete最多一次。回调抛错被隔离并记录，不阻止complete。

登录结果与资料

GoogleLoginSuccess必含errSubject、errCode=0、errMsg、requestId、platform、非空idToken。userId、email、displayName、givenName、familyName、avatarUrl可为null。Android选定Google ID SDK的id只有邮箱语义，所以userId=null；不要把邮箱当稳定sub。iOS资料来自SDK，也须以服务器验签结果为准。示例不保存令牌、不输出前后缀、不自动复制凭据。

GoogleLoginComplete只含errSubject/errCode/errMsg/requestId/platform。GoogleLoginFail额外包含nativeCode/nativeType/nativeCause/nativeStack，未知字段写unknown；详细原文先脱敏。GoogleLoginEnvironment含nativeSupported/available/hasActivity/nativeBusy/googlePlayServicesStatus/serverClientIdConfigured/iosClientIdConfigured/urlSchemeConfigured/sdkVersion/nativeBuildId/packageName/checks/limitations；Android不适用的iOS字段为false，iOS的GMS状态为-1，具体边界写入limitations。Android按当前凭据组件所需的最低Google Play服务版本检查：状态2表示需要更新服务，状态0仅表示本地服务版本检查通过，不代表网络、OAuth配置或真实授权已验证。

GoogleLoginDiagnostics含插件ID、版本及来源构建标记、生成时间、运行端、公共日志、丢弃条数、诊断失败计数和脱敏原生快照。构建标记只是对应源码的身份，不能单独证明实际安装了匹配原生包。

取消返回值

错误码说明

errSubject统一为lizhao-google-login。取消、超时均不会撤销已在Google端发生的操作；超时的外部结果保持未知。缺token、坏回执、配置失败均不作为登录成功。

注意事项

宿主、平台与验证范围

开发与既有本地验证使用 HBuilderX 5.33.2026102401，最低引擎声明见 uni_modules/lizhao-google-login/package.json，不推定更早版本兼容。市场兼容性使用 √（支持）、-（待确认）和 x（不支持）：

市场如果要求 uni-app x 至少一个运行平台标为支持，需先完成该平台的真实登录验证，再按结果调整；不要仅为通过提交校验把待确认标成支持。Android / iOS 的目录存在或资源编译通过也不代表真实登录已验收。

固定依赖与环境

SDK 不需手动拷入工程，依赖许可与来源见 uni_modules/lizhao-google-login/THIRD-PARTY-NOTICES.md。Android 采用 Credential Manager 的 Google 身份能力，接入前置条件参考 Google Android 身份登录文档。

原生基座、生命周期与隐私

日志失败不会改变业务 success / fail / complete 语义；诊断报告保留可取得的错误类型、原因与堆栈并先脱敏。不要在自己的业务日志中明文打印 ID Token、邮箱、完整回跳 URL 或 nonce。登录按钮使用官方来源图标，遵循 Google 品牌规范；Google 及相关标识属于其权利人，本插件不表示获得 Google 认可。

本地语法、资源导出、原生生成物、独立测试壳、匹配宿主基座与真实账号业务是不同验证层级。未完成真实 OAuth、后端验签、Apple 编译或设备剪贴板检查时，应按上面的清单由开发者补验，不记为已通过。

作者系列 UTS 插件

以下列表由项目核实的已发布清单生成；本插件尚未上架，暂不加入系列清单。