# @capawesome/capacitor-google-sign-in 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/

版本：0\.1\.4
npm 元数据更新时间：2026-09-02T08:22:27.883Z
中文译文更新时间：2026-11-09T02:34:14.528Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-google-sign-in
原文对照：https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/?lang=original
项目主页：https://github.com/capawesome-team/capacitor-plugins#readme
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：135 kB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-02-16T08:02:24.280Z
- 最新版本发布：2026-09-02T08:22:27.576Z
- 近 30 天下载量：97096（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

在Android,iOS,和Web上与Google签约的电容插件.

## 安装

```sh
npm install @capawesome/capacitor-google-sign-in
```

也可以使用：`pnpm add @capawesome/capacitor-google-sign-in`、`yarn add @capawesome/capacitor-google-sign-in`、`bun add @capawesome/capacitor-google-sign-in`

## README

# Google 签名插件

用 Google 登录的非官方 Capacitor 插件。 \[^1\]

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

Capacitor Google Sign-In插件是Capacitor应用程序最完整的Google认证解决方案之一. 以下是一些关键特征:

-   🖥️ **跨平台**:支持Android,iOS,和Web.
-   🔐 **认证**:在用户中用他们的Google账户签名,并获得ID标志(JWT).
-   🔑 **授权**:可选地请求 OAuth 瞄准镜以获取访问令牌和服务器认证码.
-   👤 **用户配置**:检索用户的电子邮件,显示姓名,配置图片等.
-   🛡️ **诺斯支持**:在Android和Web上使用自定义的非ce来防止回放攻击.
-   🪶 **轻巧**:只有一个依赖和零个不必要出血.
-   🚨 **错误代码**:提供详细的出错代码,以更好地处理出错.
-   🤝 **兼容性**: 与 [苹果签名 - 单位](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/) 财务报告和审定财务报表 [奥奥特](https://capawesome.io/docs/sdks/capacitor/oauth/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

Google Sign-In插件通常在用户应当以其现有的Google账户签名的地方使用,例如:

-   **社会登录**:让用户用他们的Google账户在您的应用程序上签名,而不是创建新的密码.
-   **后端认证**: 将ID标志(JWT)发送到后端验证用户身份.
-   **谷歌 API 访问**: 请 OAuth 范围代表用户获得访问令牌以访问Google API.
-   **服务器端 API 访问**: 在您的后端交换服务器认证码, 用于访问和刷新令牌 .
-   **配置文件预填**: 使用用户的电子邮件, 显示名称和配置图片, 在您的应用程序中预先填入他们的配置 .

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.1.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 指南

-   [如何使用 Capacittor 与 Google 签名](https://capawesome.io/blog/how-to-sign-in-with-google-using-capacitor/)

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-google-sign-in` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-google-sign-in
npx cap sync
```

在所有的平台上,你的品牌必须是 [已核实](https://support.google.com/cloud/answer/13463073) 您的应用程序名称将使用 Google 同意屏幕显示在标志上 .

### 机器人

创建一个 **机器人** 用户端 [谷歌云控台](https://console.cloud.google.com/apis/credentials) 在与您的网络客户端相同的工程中 :

-   **软件包名称**:您的应用程序的应用程序ID(例如. `com.example.app`),定义如下: `android/app/build.gradle`。 。 。 .
-   **SHA-1 证书指纹**:签名应用的证书的指纹.

**请注意**:Android客户端ID从未传递给插件,因为 `initialize(...)` 总是收到 **网络** 客户身份 Android客户端必须仍然存在并匹配应用,否则登录入流失败.

需要使用的 SHA-1 指纹取决于应用程序的签名方式 :

-   **本地调试构建**:调试键盘的指纹. 打印出来 `keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android`。 。 。 .
-   **通过 Google Play 分发的构建**: 指纹 **应用程序签名密钥**,而不是上传密钥。 在 Google 游戏控制台下找到它 `Test and release` › `Setup` › `App signing`。 。 。 .

为您想要支持的每个指纹添加 OAuth 客户端 。 缺失的指纹是导致登录流失败的最常见原因.

#### 变量

此插件将使用以下工程变量( 在您的应用程序中定义) `variables.gradle` 文件名 :

-   `$androidxCredentialsVersion` 版本 `androidx.credentials:credentials` (默认 : `1.5.0`(中文(简体) )
-   `$googleIdVersion` 版本 `com.google.android.libraries.identity.googleid:googleid` (默认 : `1.1.1`(中文(简体) )
-   `$playServicesAuthVersion` 版本 `com.google.android.gms:play-services-auth` (默认 : `21.5.0`(中文(简体) )

### iOS系统

添加数据 `GIDClientID` 键 `ios/App/App/Info.plist` google Cloud Console 的 iOS 客户端标识文件 :

```xml
<key>GIDClientID</key>
<string>YOUR_IOS_CLIENT_ID</string>
```

您还需要为您的 iOS 客户端ID 添加 URL 方案 `ios/App/App/Info.plist` 文件 :

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.googleusercontent.apps.YOUR_IOS_CLIENT_ID</string>
    </array>
  </dict>
</array>
```

替换 `YOUR_IOS_CLIENT_ID` 与来自Google Cloud Console的倒置客户端ID(例如. `com.googleusercontent.apps.123456789-abc`) (中文(简体) ).

## 配置

此插件不需要配置 .

## 使用量

以下示例显示如何初始化插件,在用户中签名和签名,并完成Web上的登录流.

### 初始化插件

打电话 `initialize(...)` 在所有其他方法之前 这个 `clientId` 一定是个 **网络客户端ID** 从Google Cloud Console在所有平台上,甚至在Android和iOS上. 可选规定 `scopes` 以请求授权,从而在登录结果中允许访问令牌和服务器认证码:

```typescript
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const initialize = async () => {
  await GoogleSignIn.initialize({
    clientId: '123456789-abc.apps.googleusercontent.com',
    scopes: ['https://www.googleapis.com/auth/userinfo.profile'],
  });
};
```

### 在用户中签名

启动"Google Sign-In"流程并取回"ID"(JWT)和用户配置. 注意在网络上

```typescript
import { ErrorCode, GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const signIn = async () => {
  try {
    const result = await GoogleSignIn.signIn();
    console.log(result.idToken);
    console.log(result.userId);
    console.log(result.email);
    console.log(result.displayName);
    console.log(result.accessToken);
    console.log(result.serverAuthCode);
  } catch (error) {
    if (error.code === ErrorCode.SignInCanceled) {
      console.log('The user canceled the sign-in flow.');
    } else if (error.code === ErrorCode.NoCredentialAvailable) {
      console.log('No Google account is available on this device.');
    } else if (error.code === ErrorCode.ProviderConfigurationError) {
      console.log('Google Play services is not available or not up to date.');
    } else {
      console.log('Another error occurred:', error);
    }
  }
};
```

### 完成网络上的登录流程

在网络上,应用程序被重定向回 `redirectUrl` 用户签名后。 打电话 `handleRedirectCallback()` 在那里可以将授权代码交换为符号并完成登录流. 仅在网上提供 :

```typescript
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';
import { Capacitor } from '@capacitor/core';

const handleRedirectCallback = async () => {
  if (Capacitor.getPlatform() !== 'web') {
    return;
  }
  const result = await GoogleSignIn.handleRedirectCallback();
  console.log(result.idToken);
  console.log(result.userId);
  console.log(result.email);
  console.log(result.displayName);
  console.log(result.accessToken);
  console.log(result.serverAuthCode);
};
```

### 签名用户

签名当前用户 :

```typescript
import { GoogleSignIn } from '@capawesome/capacitor-google-sign-in';

const signOut = async () => {
  await GoogleSignIn.signOut();
};
```

## API 密码

-   [`handleRedirectCallback()`](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-handleredirectcallback)
-   [`initialize(...)`](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-initialize)
-   [`signIn(...)`](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-signin)
-   [`signOut()`](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-signout)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-interfaces)

### 手柄重定向调用( C)

```typescript
handleRedirectCallback() => Promise<SignInResult>
```

处理 OAuth 提供者的重定向调用.

当应用程序从 OAuth 提供者重定向回时,必须调用这种方法 . 它将授权代码交换为令牌并返回登录结果.

仅在Web上提供.

**回返情况:** `Promise<[SignInResult](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-signinresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 初始化(...)

```typescript
initialize(options: InitializeOptions) => Promise<void>
```

初始化Google Sign-In插件.

这种方法必须在所有其他方法之前使用一次.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[InitializeOptions](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-initializeoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 签名IN(...)

```typescript
signIn(options?: SignInOptions | undefined) => Promise<SignInResult>
```

启动Google Sign-In流量.

在Web上,这可以重定向到Google OAuth的授权页面. 承诺永远不会在网络上解决。 用户签名后, 应用程序将重定向回 `redirectUrl`。 。 。 . 使用 `handleRedirectCallback()` 要完成登录流程.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SignInOptions](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-signinoptions)` |

**回返情况:** `Promise<[SignInResult](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-signinresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 符号输出( C)

```typescript
signOut() => Promise<void>
```

签名当前用户 .

在Android上,这清除了认证状态. 在iOS上,这个标志出自Google Sign-In SDK. 在网络上,这是不开放的.

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 签名结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`idToken`** | `string` | 由Google返回的ID标志 (JWT). 此符号可以发送到您的后端进行校验 . | 0.1.0 (中文(简体) ) |
| **`userId`** | `string` | 用户Google账户的独特标识符. | 0.1.0 (中文(简体) ) |
| **`email`** | `string | null` | 用户的电子邮件地址. | 0.1.0 (中文(简体) ) |
| **`displayName`** | `string | null` | 用户的显示名(全名). | 0.1.0 (中文(简体) ) |
| **`givenName`** | `string | null` | 用户的给定名 (名). | 0.1.0 (中文(简体) ) |
| **`familyName`** | `string | null` | 用户姓(上名). | 0.1.0 (中文(简体) ) |
| **`imageUrl`** | `string | null` | 用户配置图片的 URL. | 0.1.0 (中文(简体) ) |
| **`accessToken`** | `string | null` | 访问 Google API 的访问符 。 仅在 `scopes` 配置为 `initialize()`。 。 。 . | 0.1.0 (中文(简体) ) |
| **`serverAuthCode`** | `string | null` | 在您的后端可以交换的服务器认证代码, 用于访问和刷新令牌 。 只有在Android和iOS上可以使用时 `scopes` 配置为 `initialize()`。 。 。 . | 0.1.0 (中文(简体) ) |

#### 初始化选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`clientId`** | `string` | 来自Google Cloud Console的网络客户端ID. 在Android上,这个作为服务器客户端ID传递给证书管理器API和授权客户端API. 在iOS上,它被用作Google Sign-In SDK的服务器客户端ID. 在Web上,这个用于初始化Google Sign-In JavaScript API. **请注意**:这必须是所有平台,甚至Android和iOS上的网络客户端ID. | 0.1.0 (中文(简体) ) |
| **`redirectUrl`** | `string` | 在 OAuth 流后重定向到的 URL 。 仅在Web上提供. | 0.1.0 (中文(简体) ) |
| **`scopes`** | `string[]` | OAuth 范围请求 。 如果提供,插件除了认证外还会请求授权. 这样可以 `accessToken` 财务报告和审定财务报表 `serverAuthCode` 在报到结果. | 0.1.0 (中文(简体) ) |

#### 签名选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`nonce`** | `string` | 防止重放攻击的无能 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |

## 警卫

此插件处理 OAuth 流并返回给您的应用程序的符号 。 为保证融入安全,请注意以下情况:

-   **需要服务器侧符号验证 .** 这个 `idToken` (JWT)为: **没有** 验证客户端。 您的后端 **必须** 使用 [谷歌的公用钥匙](https://www.googleapis.com/oauth2/v3/certs) 在信任任何权利要求之前(例如:. `userId`, (中文(简体) ), `email`) (中文(简体) ). 在没有服务器端验证的情况下,从不使用客户端符号数据进行授权决定.
-   **交换 `serverAuthCode` 在你的后门.** 如果使用瞄准镜,请发送 `serverAuthCode` 到你的后端,并在那里交换它 访问和刷新符号。 永远不要交换客户端 因为这会暴露你的客户秘密.

## 财务问题

### 这个插件与其他Google Sign-In插件有什么区别?

这个插件是为Google Sign-In而专门设计的,并专注于提供具有最新平台功能的干净而现代的API. 以下是一些关键差异:

-   **跨平台**:支持Android,iOS,和Web.
-   **轻巧**: 无不必要的依赖。 只是Google的签名,没有别的.
-   **无折旧的 API**:使用最新的平台API(Android上的信用管理器,iOS上的Google Sign-In SDK).
-   **认证 + 授权**:支持单流中的认证(ID sorders)和授权(access sorders,服务器认证代码).
-   **错误代码**: 为正确处理错误提供打出的错误代码.
-   **在网络上重定向流量**:使用重定向的OAuth流来代替弹出,从而产生更可靠和更方便用户的经验.

### 为什么我需要Android和iOS上的网络客户端ID?

这个 `clientId` 选项必须是来自所有平台的 Google Cloud Console 的网络客户端ID。 在Android上,它作为服务器客户端ID被传递到证书管理器API和授权客户端API. 在iOS上,它被用作Google Sign-In SDK的服务器客户端ID. 在 iOS 上,您通过 `GIDClientID` 键 `Info.plist` 文件,参见 [安装](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-installation) 节.

### 为什么 `signIn` 承诺永远不要在网络上解决?

在Web上,插件使用基于重定向的OAuth流. 这个 `signIn(...)` 方法重定向到Google OAuth授权页面,因此承诺永远无法解决. 用户签名后,应用程序会重新定向到 `redirectUrl` 你必须打电话 `handleRedirectCallback()` 以完成登录流程,参见 [使用示例](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-complete-the-sign-in-flow-on-the-web) 见上文.

### 我怎么才能得到谷歌API的登录符??

配置 `scopes` 选项 `initialize(...)` 方法。 然后,插件除了认证之外,还要求授权,因为认证允许 `accessToken` 财务报告和审定财务报表 `serverAuthCode` 属性。 如果您需要访问并刷新后端上的符号,请交换 `serverAuthCode` 从来没有客户端,如 [警卫](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-security) 节.

### 为什么Android的签入流量在选择账户后就失败了?

如果取账器打开,但一旦取出一个账户,流量就会出故障,则该应用极有可能丢失匹配的Android OAuth客户端. 查找日志输出中的以下条目之一 :

```
Auth.Api.Credentials: colz: [8] Unknown error [status=UNREGISTERED_ON_API_CONSOLE].
Auth.Api.Credentials: colz: [16] Account reauth failed.
```

Google Play 服务将此报告为取消, 因此插件拒绝使用 `SIGN_IN_CANCELED` 错误代码和 `Account reauth failed` 作为错误消息。 确保Android OAuth客户端对签名应用的证书的软件包名称和SHA-1指纹存在,详情见: [安装](https://npmcn.com/package/%40capawesome/capacitor-google-sign-in/#readme-android) 节。 通过Google Play分发的构建必须使用应用程序签名密钥的指纹,而不是上传密钥.

## 相关插件

-   [苹果签名 - 单位](https://capawesome.io/docs/sdks/capacitor/apple-sign-in/):用他们的Apple账户在用户中签名.
-   [脸书签名 单位](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/):在用户中用他们的Facebook账户签名.
-   [奥奥特](https://capawesome.io/docs/sdks/capacitor/oauth/): 与任何 OAuth 2. 0 和 OpenID 连接供应商通信 .
-   [密码](https://capawesome.io/docs/sdks/capacitor/passkeys/):根据WebAuthn标准创建并认证了密码.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/google-sign-in/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/google-sign-in/LICENSE)。 。 。 .

\[^1\]: 本项目不附属于Google Inc.或其任何子公司或子公司,不由Google Inc.认可、赞助或核准.

## 常见问题

### @capawesome/capacitor-google-sign-in 是什么？

在Android,iOS,和Web上与Google签约的电容插件\.

### 如何安装 @capawesome/capacitor-google-sign-in？

在项目目录运行 npm install @capawesome/capacitor-google-sign-in，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-google-sign-in 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-google-sign-in 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-google-sign-in 可以商用吗？

@capawesome/capacitor-google-sign-in 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-google-sign-in 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-google-sign-in 在 2026/10/09 – 2026/11/07 这 30 天内被下载 97,096 次，日均约 3,237 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-google-sign-in 还在维护吗？

最新版本 0\.1\.4 发布于 2026/09/02（2 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/02/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。