# @capacitor-firebase/app-check 中文文档

规范地址：https://npmcn.com/package/%40capacitor-firebase/app-check/

版本：8\.6\.0
npm 元数据更新时间：2026-10-31T07:05:16.756Z
中文译文更新时间：2026-11-09T02:30:22.109Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capacitor-firebase/app-check
原文对照：https://npmcn.com/package/%40capacitor-firebase/app-check/?lang=original
项目主页：https://capawesome.io/
源码仓库：https://github.com/capawesome-team/capacitor-firebase

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

- 包体积（解压后）：103 kB，29 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：firebase ^12\.6\.0，@capacitor/core \>=8\.0\.0
- 首次发布：2022-11-05T22:50:28.103Z
- 最新版本发布：2026-10-31T07:05:16.426Z
- 近 30 天下载量：115106（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 13 个）

## 中文简介

用于Firebase App检查Android,iOS,和Web的电容插件.

## 安装

```sh
npm install @capacitor-firebase/app-check
```

也可以使用：`pnpm add @capacitor-firebase/app-check`、`yarn add @capacitor-firebase/app-check`、`bun add @capacitor-firebase/app-check`

## README

# 控制器 Firebase 应用程序检查插件

非官方电容插件 [Firebase 应用程序检查](https://firebase.google.com/docs/app-check)\[^1\]

[![Ship a fix in one command with Capawesome Cloud Live Updates, no store review](https://capawesome.io/assets/banners/cloud-ship-a-fix-in-one-command.png)](https://capawesome.io/)

## 使用大小写

Firebase App Check 插件通常用于验证对后端的请求来自您真实的应用程序,例如:

-   **保护消防基地资源**: 确保只有您的真应用程序才能通过Play Guide, App Attest, 或 reCAPTCHA v3 的证明请求, 获取像 Cloud Firestore 或 Cloud 函数等服务.
-   **保护自定义后端**: 获取 App 检查符 `getToken(...)` 并随请求一起发送到您的后端用于服务器侧验证.
-   **自动刷新令牌**: 保留应用程序 检查最新的符号 `setTokenAutoRefreshEnabled(...)` 并通过 `tokenChanged` 听着.
-   **地方发展**: 使用调试提供者在模拟器等未经验证的设备上测试您的应用程序.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 7.x.x (中文(简体) ) | 7.x.x (中文(简体) ) | 折旧 |
| 6.x.x (中文(简体) ) | 6.x.x (中文(简体) ) | 折旧 |
| 5.x.x (中文(简体) ) | 5.x.x (中文(简体) ) | 折旧 |

## 指南

-   [Firebase App 控制器 App 检查](https://capawesome.io/blog/capacitor-firebase-app-check-guide/): 设置 Play Guide, App Attest, 和 reCAPTCHA 供应商, 并用此插件校验令牌服务器侧.
-   [如何在电容App中使用火把](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/):对"火地"服务App Check的巡演,一旦执行完毕就结束了保护.

## 安装

你可以用我们的 **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 `@capacitor-firebase/app-check` plugin in my project.
```

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

```bash
npm install @capacitor-firebase/app-check firebase
npx cap sync
```

如果您还没有将 Firebase 添加到您的项目中([机器人](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) 编号 : [iOS系统](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) 编号 : [网页](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)) (中文(简体) ).

### 机器人

见 [设置您的防火基地项目](https://firebase.google.com/docs/app-check/android/play-integrity-provider#project-setup) 并遵守指示 正确设置您的应用程序.

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$firebaseAppCheckPlayIntegrityVersion` 版本 `com.google.firebase:firebase-appcheck-playintegrity` (默认 : `19.0.1`(中文(简体) )
-   `$firebaseAppCheckDebugVersion` 版本 `com.google.firebase:firebase-appcheck-debug` (默认 : `19.0.1`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

### iOS系统

打开 **iOS 14及以后**,参见 [设置您的防火基地项目](https://firebase.google.com/docs/app-check/ios/app-attest-provider#project-setup) 并遵守指示 正确设置您的应用程序.

打开 **iOS 13**,参见 [设置您的防火基地项目](https://firebase.google.com/docs/app-check/ios/devicecheck-provider#project-setup) 并遵守指示 正确设置您的应用程序.

确保上传到Firebase的私钥(\*.p8) `DeviceCheck` 选择为服务.

#### Swift 软件包管理器

在您的 `capacitor.config.json` (或 `capacitor.config.ts`) 避免 [SwiftPM 软件包识别相撞](https://github.com/capawesome-team/capacitor-firebase/issues/959)数字 :

```json
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/app-check": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**请注意**目标 `packageOptions` 支持需要控制器 CLI **8.4.0+ (中文(简体) )**。 。 。 .

### 网页

见 [设置您的防火基地项目](https://firebase.google.com/docs/app-check/web/recaptcha-provider#project-setup) 并遵守指示 正确设置您的应用程序.

## 配置

此插件不需要配置 .

## 火基地 JavaScript SDK

[给](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app-check/docs/firebase-js-sdk.md) 您可以找到如何使用 Firebase JS SDK 插件的信息.

## 演示

这里有一个实例: [robingenz/电容器-火力基地-插座-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## 使用量

以下实例显示如何初始化 App Check, 获取当前符号, 启用自动符号刷新, 并聆听符号更改 .

### 初始化 App 检查

激活应用程序检查您的应用程序 。 每个应用程序只能调用一次。 在网络上,通过一个提供者,例如 `ReCaptchaV3Provider`在Android和iOS上,使用本地证明提供者:

```typescript
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';
import { ReCaptchaV3Provider } from '@capacitor-firebase/app-check';
import { Capacitor } from '@capacitor/core';

const initialize = async () => {
  await FirebaseAppCheck.initialize({
    provider: Capacitor.getPlatform() === 'web' ? new ReCaptchaV3Provider('myKey') : undefined,
  });
};
```

### 获取当前 App 检查令牌

获取当前 AppCheck 令牌, 例如将其发送到您的后端 。 设定 `forceRefresh` 改为 `true` 如果您总是想要取出一个新的符号而不是缓存的符号:

```typescript
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

const getToken = async () => {
  const { token } = await FirebaseAppCheck.getToken({
    forceRefresh: false,
  });
  return token;
};
```

### 启用自动令牌刷新

设定是否根据需要自动刷新 App Check 令牌 :

```typescript
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

const setTokenAutoRefreshEnabled = async () => {
  await FirebaseAppCheck.setTokenAutoRefreshEnabled({ enabled: true });
};
```

### 听值更改

当 App 检查令牌更改时得到通知 :

```typescript
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

const addTokenChangedListener = async () => {
  await FirebaseAppCheck.addListener('tokenChanged', event => {
    console.log('tokenChanged', { event });
  });
};
```

### 删除所有听众

删除此插件的所有听众 。 仅在网上提供 :

```typescript
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';

const removeAllListeners = async () => {
  await FirebaseAppCheck.removeAllListeners();
};
```

## API 密码

-   [`getToken(...)`](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-gettoken)
-   [`initialize(...)`](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-initialize)
-   [`setTokenAutoRefreshEnabled(...)`](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-settokenautorefreshenabled)
-   [`addListener('tokenChanged', ...)`](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-addlistenertokenchanged-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-type-aliases)

### 获取托肯(...)

```typescript
getToken(options?: GetTokenOptions | undefined) => Promise<GetTokenResult>
```

获取当前 App Check 令牌 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetTokenOptions](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-gettokenoptions)` |

**回返情况:** `Promise<[GetTokenResult](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-gettokenresult)>`

**自:** 1.3.0 (单位:千美元)

* * *

### 初始化(...)

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

激活给定应用程序的 App 检查 . 每个应用程序只能呼叫一次.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[InitializeOptions](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-initializeoptions)` |

**自:** 1.3.0 (单位:千美元)

* * *

### 设置 Token 自动重新启用(...)

```typescript
setTokenAutoRefreshEnabled(options: SetTokenAutoRefreshEnabledOptions) => Promise<void>
```

设定是否自动刷新 App Check 令牌 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetTokenAutoRefreshEnabledOptions](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-settokenautorefreshenabledoptions)` |

**自:** 1.3.0 (单位:千美元)

* * *

### 添加倾听器( “ token Changed' ,...)

```typescript
addListener(eventName: 'tokenChanged', listenerFunc: TokenChangedListener) => Promise<PluginListenerHandle>
```

当 App Check 令牌更改时调用 .

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'tokenChanged'` |
| **`listenerFunc`** | `[TokenChangedListener](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-tokenchangedlistener)` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-pluginlistenerhandle)>`

**自:** 1.3.0 (单位:千美元)

* * *

### 删除所有收听器( )

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

删除此插件的所有听众 .

仅供Web使用.

**自:** 1.3.0 (单位:千美元)

* * *

### 接口

#### 获取托肯结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`token`** | `string` | 以 JWT 为格式的 App Check 令牌 . | 1.3.0 (单位:千美元) |
| **`expireTimeMillis`** | `number` | 自纪元后,该标志将在毫秒后过期。 仅供Android和iOS使用. | 1.3.0 (单位:千美元) |

#### 获取托肯选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`forceRefresh`** | `boolean` | 若为 `true`,将总是试图取出新的标志。 若为 `false`,如果在存储中找到,将使用缓存的令牌. | `false` | 1.3.0 (单位:千美元) |

#### 初始化选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`debug`** | `boolean` | 若为 `true`,则使用调试提供者。 ⚠️ **请注意**:调试提供者允许从未经验证的设备访问您的 Firebase 资源 。 在您的应用软件的生产建设中不要使用调试提供者,也不要与不信任的方分享你的调试建筑. ⚠️ **折旧**: 使用 `debugToken` 换句话说 此选项将在下一个主要版本被删除 。 更多信息: [https://firebase.google.com/docs/app-check/web/debug-professor 页面存档备份,存于互联网档案馆](https://firebase.google.com/docs/app-check/web/debug-provider) | `false` | 1.3.0 (单位:千美元) |
| **`debugToken`** | `string | boolean` | 若为 `true`,则使用调试提供者。 打开 **网页**,您也可以设置一个预定义的调试符字符串,而不是 `true`。在Android和iOS上,您必须为此使用环境变量。 ⚠️ **请注意**:调试提供者允许从未经验证的设备访问您的 Firebase 资源 。 在您的应用软件的生产建设中不要使用调试提供者,也不要与不信任的方分享你的调试建筑. | `false` | 7.1.0 (中文(简体) ) |
| **`isTokenAutoRefreshEnabled`** | `boolean` | 若为 `true`, SDK 自动刷新 App Check 令牌 . | `false` | 1.3.0 (单位:千美元) |
| **`provider`** | `any` | 用于 App Check 的提供者 。 一定是这样 `ReCaptchaV3Provider`, (中文(简体) ), `ReCaptchaEnterpriseProvider`,或 `CustomProvider`。仅可用于Web. | `ReCaptchaV3Provider` | 7.1.0 (中文(简体) ) |
| **`siteKey`** | `string` | ReCAPTCHA v3站点密钥(公钥). 此选项在 `provider` 已经设定。 仅供Web使用. |  | 1.3.0 (单位:千美元) |

#### 设置托肯自动重新启用选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`enabled`** | `boolean` | 若为 `true`, SDK 自动刷新 App Check 令牌 。 此选项覆盖初始化时设置的任何值 AppCheck () . | 1.3.0 (单位:千美元) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### Token 变换事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`token`** | `string` | 以 JWT 为格式的 App Check 令牌 . | 1.3.0 (单位:千美元) |

### 类型异名

#### 已更改 听众

召回以接收符号更改事件 .

`(event: [TokenChangedEvent](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-tokenchangedevent)): void`

## 测试

### 机器人

遵循这些步骤来测试您在真实设备上的执行情况 :

1.  启动Android设备的应用程序.
2.  运行以下命令从机器人日志中获取您的临时秘密 :

```
adb logcat | grep DebugAppCheckProvider
```

输出应该是这样的:

```
D DebugAppCheckProvider: Enter this debug secret into the allow list in
the Firebase Console for your project: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
```

1.  接下来,打开 [App 检查工程](https://console.firebase.google.com/u/0/project/_/appcheck/apps) 在 Firebase 控制台中从您的应用程序的外溢菜单中选择管理调试符 。 然后,从输出中注册调试密钥 .

## 财务问题

### 此插件使用哪些验证提供者 ?

在Android上,插件使用 [播放完整性](https://firebase.google.com/docs/app-check/android/play-integrity-provider#project-setup) 供养. 在iOS上,它使用 [应用测试](https://firebase.google.com/docs/app-check/ios/app-attest-provider#project-setup) 关于iOS 14, 稍后 [设备检查](https://firebase.google.com/docs/app-check/ios/devicecheck-provider#project-setup) iOS 13号机 在网络上,它使用 [reCAPTCHA v3 (英语)](https://firebase.google.com/docs/app-check/web/recaptcha-provider#project-setup) 默认,但您也可以通过 `ReCaptchaEnterpriseProvider` 或者说 `CustomProvider` 实例 `provider` 选项.

### 我怎么能测试App检查器和其他未经验证的装置?

通过设置调试提供者 `debugToken` 选项 `initialize(...)` 方法。 在Android上,你可以从设备日志中抓取临时调试密钥并将其注册到Firebase Console(参见 [测试](https://npmcn.com/package/%40capacitor-firebase/app-check/#readme-testing)) (中文(简体) ). 在您的应用程序生产构建中不要使用调试提供者, 也不要与未信任的方共享您的调试构建, 因为它允许从未验证的设备获取您的 Firebase 资源 .

### 我怎么用AppCheck保护自己的后端?

打电话 `getToken(...)` 以 JWT 格式检索当前 App Check 令牌并连同请求一起发送到您的后端的方法, 您可以在此验证其服务器侧。 使用 `tokenChanged` 听者可以在符号更改时得到通知.

### 为什么我的 App Check 令牌没有自动刷新?

自动令牌刷新默认已禁用 。 你可以启动它与 `isTokenAutoRefreshEnabled` 选项 `initialize(...)` 方法或任何时候 `setTokenAutoRefreshEnabled(...)` 方法.

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

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

## 相关插件

-   [Firebase 验证](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Firebase 认证的非官方电容插件.
-   [火地云炉](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-firestore/):Firebase Cloud Firestore的非官方电容插件.
-   [火基地云函数](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/):Firebase云函数的非官方电容插件.
-   [火地云存储](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/):Firebase云存储的非官方电容插件.

## 通讯

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

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app-check/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/app-check/LICENSE)。 。 。 .

\[^1\]: 这个项目不附属于Google LLC或其任何子公司或子公司,也不获得其认可、支持、赞助或批准.

## 常见问题

### @capacitor-firebase/app-check 是什么？

用于Firebase App检查Android,iOS,和Web的电容插件\.

### 如何安装 @capacitor-firebase/app-check？

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

### @capacitor-firebase/app-check 支持 TypeScript 吗？

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

### @capacitor-firebase/app-check 支持 ESM 还是 CommonJS？

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

### @capacitor-firebase/app-check 可以商用吗？

@capacitor-firebase/app-check 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @capacitor-firebase/app-check 的下载量有多少？

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

### @capacitor-firebase/app-check 还在维护吗？

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