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

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

版本：0\.1\.5
npm 元数据更新时间：2026-11-07T05:35:28.858Z
中文译文更新时间：2026-11-09T02:32:57.301Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：112 kB，40 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-03-01T14:48:30.313Z
- 最新版本发布：2026-11-07T05:35:28.502Z
- 近 30 天下载量：98252（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

在Android,iOS,和Web上与苹果签约的Capacitor插件.

## 安装

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

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

## README

# 苹果签名插件

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

[![Try Capawesome Cloud free for 14 days — iOS builds without a Mac](https://capawesome.io/assets/banners/cloud-free-trial-capacitor-apps.png)](https://capawesome.io/)

## 特征

Capacitor Apple Sign-In插件是Capacitor App最完整的苹果认证解决方案之一. 以下是一些关键特征:

-   🖥️ **跨平台**:支持Android,iOS,和Web.
-   🍎 **原生标志 - 单位**:在iOS上使用本土认证服务.
-   🌐 **网络视频 OAuth**:在Android上执行Apple OAuth流而无需外部依赖.
-   📧 **范围支助**:在所有平台上请求电子邮件和全名.
-   🔐 **状态( S)**:支持非ce用于回放保护并状态用于CSRF保护.
-   🪶 **轻巧**:只有一个依赖和零个不必要出血.
-   🤝 **兼容性**: 与 [谷歌签名 单位](https://capawesome.io/docs/sdks/capacitor/google-sign-in/) 财务报告和审定财务报表 [奥奥特](https://capawesome.io/docs/sdks/capacitor/oauth/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

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

## 使用大小写

Apple Sign-In插件一般用于让用户用自己的Apple ID认证,例如:

-   **用户认证**: 在Android, iOS和Web的应用程序中提供与 Apple 签名作为登录选项 .
-   **账户创建**: 使用电子邮件和全名范围在注册时请求用户的电子邮件地址和全名.
-   **后端集成**:向后端发送授权代码和ID令牌,以验证登录并创建用户会话.
-   **安全登录流量**:通过一个非ce作为回放保护,和一个用于CSRF保护的状态值.

## 兼容性

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

## 指南

-   [如何使用 Capacittor 与 Apple 签名](https://capawesome.io/blog/how-to-sign-in-with-apple-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-apple-sign-in` plugin in my project.
```

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

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

### iOS系统

添加数据 **用苹果签名** xcode 中的应用程序的能力 :

1.  在 Xcode 中打开您的应用目标 .
2.  转到 **签名能力( C)** 选项卡.
3.  点击 **\+ 能力** 添加 **用苹果签名**。 。 。 .

### 网页

插件装入 [苹果JS SDK](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js) 自动. 确定您配置了您的 Apple 服务ID , 并配置了正确的 URL 和 Web 域名 [苹果开发者门户网站](https://developer.apple.com/account/resources/identifiers/list/serviceId)。 。 。 .

## 配置

此插件不需要配置 .

## 使用量

以下例子显示如何初始化插件并和Apple一起签名.

### 初始化插件

在Android和Web上,您必须先以您的苹果服务ID初始化插件,然后再拨打 `signIn(...)`。这种方法只在Android和Web上提供:

```typescript
import { AppleSignIn } from '@capawesome/capacitor-apple-sign-in';

const initialize = async () => {
  await AppleSignIn.initialize({
    clientId: 'com.example.app.signin',
  });
};
```

### 用苹果签名

启动登录流程并接收授权代码和ID标志. 使用 `scopes` 选项以请求用户的电子邮件地址和全名,并通过一个 `nonce` 用于回放保护。 这个 `redirectUrl` 财务报告和审定财务报表 `state` 选项仅在Android和Web上提供:

```typescript
import { AppleSignIn, SignInScope } from '@capawesome/capacitor-apple-sign-in';

const signIn = async () => {
  const result = await AppleSignIn.signIn({
    scopes: [SignInScope.Email, SignInScope.FullName],
    redirectUrl: 'https://example.com/callback',
    nonce: 'random-nonce',
    state: 'random-state',
  });
  return result;
};
```

## API 密码

-   [`initialize(...)`](https://npmcn.com/package/%40capawesome/capacitor-apple-sign-in/#readme-initialize)
-   [`signIn(...)`](https://npmcn.com/package/%40capawesome/capacitor-apple-sign-in/#readme-signin)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-apple-sign-in/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-apple-sign-in/#readme-enums)

### 初始化(...)

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

初始化插件 .

这种方法必须先调用 `signIn()` 打开 **机器人** 财务报告和审定财务报表 **网页**。 。 。 .

仅在Android和Web上提供.

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

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

* * *

### 签名IN(...)

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

与苹果公司签约.

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

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

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

* * *

### 接口

#### 初始化选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`clientId`** | `string` | 用于登录的苹果服务ID. | 0.1.0 (中文(简体) ) |

#### 签名结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`authorizationCode`** | `string` | 授权代码. | 0.1.0 (中文(简体) ) |
| **`idToken`** | `string` | 身份标志 (JWT). | 0.1.0 (中文(简体) ) |
| **`user`** | `string` | 稳定的苹果用户标识符. 打开 **机器人** 财务报告和审定财务报表 **网页**,这是从JWT解码 `sub` 索赔. | 0.1.0 (中文(简体) ) |
| **`email`** | `string | null` | 用户的电子邮件地址. 打开 **iOS系统**,这个只在第一个登录时提供. | 0.1.0 (中文(简体) ) |
| **`givenName`** | `string | null` | 取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取. 打开 **iOS系统**,这个只在第一个登录时提供. | 0.1.0 (中文(简体) ) |
| **`familyName`** | `string | null` | 用户姓. 打开 **iOS系统**,这个只在第一个登录时提供. | 0.1.0 (中文(简体) ) |
| **`state`** | `string` | 签名请求的状态值 。 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |
| **`realUserStatus`** | `[RealUserStatus](https://npmcn.com/package/%40capawesome/capacitor-apple-sign-in/#readme-realuserstatus)` | 真实用户状态. 仅在iOS上可用. | 0.1.0 (中文(简体) ) |

#### 签名选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`redirectUrl`** | `string` | OAuth 重定向 URL 用于登录 。 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |
| **`scopes`** | `SignInScope[]` | 登录时请求的范围 . | 0.1.0 (中文(简体) ) |
| **`nonce`** | `string` | 用于重放保护的非曲目. | 0.1.0 (中文(简体) ) |
| **`state`** | `string` | CSRF保护的状态值. 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |

### 数字

#### 用户状态

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`LikelyReal`** | `'LIKELY_REAL'` | 使用者似乎是一个真实的人. | 0.1.0 (中文(简体) ) |
| **`Unknown`** | `'UNKNOWN'` | 系统无法确定用户是否为真人. | 0.1.0 (中文(简体) ) |
| **`Unsupported`** | `'UNSUPPORTED'` | 此平台不支持真正的用户状态 . | 0.1.0 (中文(简体) ) |

#### 签名范围

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Email`** | `'EMAIL'` | 请求用户的电子邮件地址 . | 0.1.0 (中文(简体) ) |
| **`FullName`** | `'FULL_NAME'` | 请求用户全名. | 0.1.0 (中文(简体) ) |

## 警卫

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

-   **需要服务器侧符号验证 .** 这个 `idToken` (JWT)为: **没有** 验证客户端。 您的后端 **必须** 使用 [苹果的公用钥匙](https://appleid.apple.com/auth/keys) 在信任任何权利要求之前(例如:. `user`, (中文(简体) ), `email`) (中文(简体) ). 在没有服务器端验证的情况下,从不使用客户端符号数据进行授权决定.
-   **验证 `state` 参数.** 插件通过 `state` 值通到结果,但确实 **没有** 验证它。 您的应用程序必须比较返回的 `state` 与它最初发送的用于防范CSRF攻击的值相对应.
-   **Android使用基于WebView的OAuth流.** 不同于iOS( 它使用本地 `AuthenticationServices`),Android执行使得苹果公司在WebView上的登录页面. 与系统浏览器流不同的是,WebView由应用控制并可以访问页面内容. 保证您 `redirectUrl` 使用 HTTPS 并指向您控制的一个域.

## 财务问题

### 此插件与其他 Apple Sign- In 插件有何不同 ?

这个插件是为Apple Sign-In而专门建造的,专注于提供具有最新平台功能的清洁而现代的API. 以下是一些关键差异:

-   **跨平台**:支持Android,iOS,和Web.
-   **轻巧**: 无不必要的依赖。 只是苹果签入,没有别的.
-   **无折旧的 API**: 使用最新的平台API(iOS上的认证服务).
-   **范围支助**:在所有平台上请求电子邮件和全名.
-   **错误代码**: 为正确处理错误提供打出的错误代码.

### 我是否需要在iOS上呼叫初始化?

不,那个 `initialize(...)` 方法只在Android和Web上可用,必须先调用 `signIn(...)` 设置 Apple 服务标识。 在iOS上,插件使用本地认证服务框架,不需要初始化.

### 为什么邮件和名字只在iOS上的第一个登录时返回?

在iOS上,苹果公司只提供用户的电子邮件地址,给定名和姓氏在第一个登录上;在之后的登录上,这些值是 `null`。当您第一次收到这些信息时,请务必坚持这些信息,例如在您的后端.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [脸书签名 单位](https://capawesome.io/docs/sdks/capacitor/facebook-sign-in/): 与Facebook签约.
-   [谷歌签名 单位](https://capawesome.io/docs/sdks/capacitor/google-sign-in/):与谷歌签约.
-   [奥奥特](https://capawesome.io/docs/sdks/capacitor/oauth/): 与OAuth 2.0和OpenID Connection 供应商通信.
-   [密码](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/apple-sign-in/CHANGELOG.md)。 。 。 .

## 许可证

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

\[^1\]: 本项目不隶属于苹果公司或其任何子公司或子公司,不获其认可,不获其赞助或批准.

## 常见问题

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

在Android,iOS,和Web上与苹果签约的Capacitor插件\.

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

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

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

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

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

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

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

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

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

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

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

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