react-native-nitro-google-signin

React Native Nitro Google Sign-In

Agent 技能（编码 Agent 请先安装）

npx skills add react-native-nitro-google-sign-in/google-signin -g -y

文档：https://react-native-nitro-google-sign-in.github.io/docs/agents/skill

安装软件包

bun add react-native-nitro-google-signin react-native-nitro-modules
bundle exec pod install --project-directory="ios"

需要 RN ≥ 0.76。不支持 Expo Go——请使用 expo-dev-client。

规则

主题	规则
API	使用 react-native-nitro-google-signin 中的 GoogleOneTapSignIn
先配置	在登录前调用 GoogleOneTapSignIn.configure({ webClientId })
serverAuthCode	需要在 configure() 中设置 offlineAccess: true，否则始终为 null。没有离线访问权限时，requestScopes() 仍会为设备端 API 返回 accessToken
后端	在服务器上验证每个 idToken（签名、aud、iss、exp）；如果使用 hostedDomain，请验证 JWT 的 hd
iOS 离线授权	静默调用 signIn() 会返回 serverAuthCode: null——请使用 createAccount() 获取初始代码
revokeAccess	Android：按邮箱/ID 撤销。iOS：仅限当前会话（ID 不匹配时会抛出错误）
getTokens	登录后调用；没有会话时会抛出 SIGN_IN_REQUIRED。iOS：401 后重试前调用 clearCachedAccessToken。Android：在已授予权限的情况下，可在后台任务中运行（无需 Activity）
getCurrentUser	同步调用；返回用户及其 scopes，或 null。对于现有用户，在调用 requestScopes 前检查权限范围
流程顺序	checkPlayServices → signIn → createAccount → presentExplicitSignIn
Android autoDetect	需要 google-services.json 和 com.google.gms.google-services 插件
iOS	需要 GoogleService-Info.plist 和 REVERSED_CLIENT_ID URL 方案
Expo	插件 react-native-nitro-google-signin；完成原生配置后运行 expo prebuild
原生代码变更后	重新构建应用——仅运行 Metro 不够

登录流程

import {
  GoogleOneTapSignIn,
  isNoSavedCredentialFoundResponse,
  isSuccessResponse,
} from 'react-native-nitro-google-signin'

GoogleOneTapSignIn.configure({ webClientId: 'autoDetect' })

await GoogleOneTapSignIn.checkPlayServices()
let response = await GoogleOneTapSignIn.signIn()
if (isNoSavedCredentialFoundResponse(response)) {
  response = await GoogleOneTapSignIn.createAccount()
}
if (isNoSavedCredentialFoundResponse(response)) {
  response = await GoogleOneTapSignIn.presentExplicitSignIn()
}
if (isSuccessResponse(response)) {
  const { user, idToken } = response.data
}

平台快速选择

• Expo → 插件 + app.config.js 中的 googleServicesFile → reference.md#expo
• 裸 Android → SHA-1 + 可选的 Google Services 插件 → reference.md#android
• 裸 iOS → plist + URL 方案 → reference.md#ios

故障排除

症状	可能的解决方法
DEVELOPER_ERROR（Android）	OAuth 客户端中的 SHA-1 或软件包名错误
选择账号后出现 type: 'cancelled'（Android 发布版/Play）	Android OAuth 客户端缺少 Play App Signing / 发布版 SHA-1 — 故障排除
未找到 default_web_client_id	添加 google-services.json + Gradle 插件
iOS 重定向失败	修正 REVERSED_CLIENT_ID URL scheme。在使用场景生命周期的应用中，确保 GIDSignIn.sharedInstance.handle(url) 位于 SceneDelegate.swift 中
启动时崩溃，出现 UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption（iOS 27）	Expo SDK 57：添加 expo-build-properties，并设置 ios: { enableSceneSupport: true }（SDK 58+ 中默认为启用）。Bare RN：添加 UIApplicationSceneManifest + SceneDelegate.swift — 故障排除
pod install / Expo prebuild — AppCheckCore / RecaptchaInterop（或与 Firebase App Check 冲突）	Expo：升级软件包 + prebuild --clean（插件会添加模块化标头，不会固定 AppCheckCore < 11.3）。Bare：添加 AppCheckCore/GoogleUtilities/RecaptchaInterop，并设置 :modular_headers => true — 故障排除
未找到 Nitro	重建开发客户端 / bundle exec pod install --project-directory="ios"
Android 按钮已布局但显示空白	升级软件包（进程内品牌按钮）+ 重建原生应用
登录在调试版中正常，在发布版中失败	库自带使用者 ProGuard 规则；避免使用 -keep androidx.**；测试 assembleRelease。同时检查发布版/Play SHA-1（见上方“选择账号后出现 cancelled”）

更多详情

• reference.md — API、Expo/bare 配置、错误
• examples.md — 可复制粘贴的代码片段
• 文档：https://react-native-nitro-google-sign-in.github.io/