更新记录

1.0.0（2026-07-11）

1.0.0（2026-07-11）

• 首次发布
• Google 授权登录（Android + iOS），返回 idToken / accessToken / email / userId / displayName / avatarUrl
• Apple 授权登录（iOS，原生 ASAuthorizationController）
• Google 登出（googleLogout）
• 实例式 API：getThirdpartySignin().googleLogin() / googleLogout() / appleLogin()

平台兼容性

uni-app x(4.0)

第三方登录 Google + Apple（uni-app x / UTS）

uni-thirdparty-signin 是一个 uni-app x 原生第三方登录聚合插件，一次集成同时拥有：

• Google 授权登录 —— Android + iOS
• Apple 授权登录 —— iOS（原生 ASAuthorizationController，不依赖 uni-oauth）
• Google 登出

登录成功后返回 idToken 等凭证，交给你自己的后端做身份校验换取业务 token。纯原生实现（Android → Kotlin，iOS → Swift），无 WebView、无 JS 桥接开销。

⚠️ 本插件为 UTS 插件，仅支持 uni-app x，且必须使用自定义调试基座 / 自有证书打包才能生效（标准基座不含 Google/Apple 原生依赖）。

一、平台与环境支持

• HBuilderX 4.0+
• Android 原生依赖：com.google.android.gms:play-services-auth:21.2.0
• iOS 原生依赖：CocoaPods GoogleSignIn 7.1.0 + 系统框架 AuthenticationServices

以上依赖已在插件 config.json 中声明，打自定义基座时自动拉取，无需手动配置。

二、快速开始

1. 引入插件

将 uni_modules/uni-thirdparty-signin 目录整体拷贝进你的 uni-app x 项目 uni_modules/ 下（或从插件市场导入）。

2. 调用

import { getThirdpartySignin, ThirdSignInResult } from '@/uni_modules/uni-thirdparty-signin'

const sdk = getThirdpartySignin()

// —— Google 登录 ——
const r : ThirdSignInResult = await sdk.googleLogin({
  clientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com'
})
console.log(r.idToken, r.email, r.userId)

// —— Apple 登录（仅 iOS）——
// #ifdef APP-IOS
const a : ThirdSignInResult = await sdk.appleLogin()
console.log(a.idToken, a.userId)
// #endif

// —— Google 登出 ——
await sdk.googleLogout()

3. 打自定义基座运行

标准基座无原生依赖，必须制作自定义调试基座（HBuilderX：运行 → 运行到手机或模拟器 → 制作自定义调试基座）后再运行，否则真机会报找不到原生类。

三、前置配置（关键）

3.1 Google —— Google Cloud Console

1. 打开 Google Cloud Console → 创建项目 → 「API 和服务 → 凭据」。

2. 建 OAuth 客户端 ID，你需要 3 个：

   • Web 应用：拿到的 Client ID 就是代码里传的 clientId（即 serverClientId），用于签发可发给后端校验的 idToken。两端都用这一个。
   • Android：填应用包名 + 签名证书 SHA-1（用你打包证书的 SHA-1，调试基座用 HBuilderX 默认证书的 SHA-1）。Android 端不直接用它的 ID，但必须创建，否则 Google 拒绝授权。
   • iOS：填 Bundle ID，拿到 iOS Client ID 与反转的 URL Scheme。

3. iOS 额外配置（HBuilderX manifest → App 图标/启动图旁的源码视图，或 Info.plist）：

   • 添加 GIDClientID = 你的 iOS Client ID。
   • 添加 URL Type，URL Scheme = iOS Client ID 的反转域名（形如 com.googleusercontent.apps.xxxx）。

拿不到授权 / 报 status=10：99% 是 SHA-1 或包名和 Console 里登记的不一致。调试基座与正式包证书不同，SHA-1 也不同，两者都要登记。

3.2 Apple —— Apple Developer

1. Apple Developer → Certificates, Identifiers & Profiles → 你的 App ID → 勾选 Sign In with Apple capability。
2. HBuilderX：manifest.json → App 常用其它设置 / iOS，开启 Sign in with Apple 能力（打包时写入 entitlements）。
3. Apple 登录仅 iOS，Android 端调用会直接 reject，请用 #ifdef APP-IOS 守卫按钮与调用。

四、API 文档

getThirdpartySignin(): ThirdpartySignin

获取登录管理实例。

ThirdpartySignin 实例方法

类型定义

type GoogleLoginOptions = {
  clientId : string   // Google Cloud Console「Web 应用」类型 OAuth Client ID
}

type ThirdSignInResult = {
  provider    : string   // "google" | "apple"
  idToken     : string   // OIDC id_token —— 发给后端校验的核心凭证
  accessToken : string   // iOS Google 有值；Android Google、Apple 为空
  email       : string   // Apple 仅首次授权返回
  userId      : string   // 平台稳定唯一标识（Google: sub/id；Apple: user）
  displayName : string   // Apple 仅首次授权返回
  avatarUrl   : string   // Google 头像 URL；Apple 为空
}

失败处理

登录/登出失败时 Promise reject(new Error(message))，用 try/catch 或 .catch() 捕获。常见 message：

五、完整示例

<template>
  <view class="wrap">
    <button @click="onGoogle">Google 登录</button>
    <!-- #ifdef APP-IOS -->
    <button @click="onApple">Apple 登录</button>
    <!-- #endif -->
    <button @click="onLogout">Google 登出</button>
    <text>{{ msg }}</text>
  </view>
</template>

<script setup>
  import { ref } from 'vue'
  import { getThirdpartySignin, ThirdSignInResult, GoogleLoginOptions } from '@/uni_modules/uni-thirdparty-signin'

  const GOOGLE_CLIENT_ID = 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com'
  const sdk = getThirdpartySignin()
  const msg = ref<string>('')

  const onGoogle = async () : Promise<void> => {
    try {
      const r : ThirdSignInResult = await sdk.googleLogin({ clientId: GOOGLE_CLIENT_ID } as GoogleLoginOptions)
      msg.value = 'Google: ' + r.email + ' / ' + r.userId
      // TODO: 把 r.idToken 发给后端校验
    } catch (e) {
      msg.value = '失败：' + (e as Error).message
    }
  }

  // #ifdef APP-IOS
  const onApple = async () : Promise<void> => {
    try {
      const r : ThirdSignInResult = await sdk.appleLogin()
      msg.value = 'Apple: ' + r.userId
    } catch (e) {
      msg.value = '失败：' + (e as Error).message
    }
  }
  // #endif

  const onLogout = async () : Promise<void> => {
    await sdk.googleLogout()
    msg.value = '已登出'
  }
</script>

六、常见问题（FAQ）

Q：点了登录一直转圈、无回调？ iOS Apple 登录若 helper 未被强引用会提前释放导致此现象——本插件已用全局强引用规避。若 Google 登录转圈，多为 iOS 未配置 URL Scheme 或 GIDClientID。

Q：Android 报 status=10？ Console 的 Android OAuth 客户端 SHA-1 / 包名与当前运行包不一致。调试基座、正式包 SHA-1 不同，都要在 Console 登记。

Q：Apple 登录第二次拿不到 email / 姓名？ 正常。Apple 只在首次授权返回 email 和 fullName，之后仅返回 user（稳定 id）。请首次就把 email/姓名入库。

Q：idToken 怎么用？ 发给你自己的后端，后端用 Google / Apple 的公钥验签 + 校验 aud（须等于你的 clientId）后，签发业务 token。不要信任前端直接返回的 email。

Q：能用在传统 uni-app（非 x）吗？ 不能。本插件是 UTS + uni-app x 专用。

七、更新日志

见 changelog.md。

八、许可与支持

• 定价 / 联系方式见插件市场页面。
• 问题反馈请在插件市场评论区或通过作者联系方式沟通。