# @capgo/capacitor-webview-guardian 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-webview-guardian/

版本：8\.1\.4
npm 元数据更新时间：2026-10-19T12:33:45.389Z
中文译文更新时间：2026-11-09T03:43:00.168Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-webview-guardian
原文对照：https://npmcn.com/package/%40capgo/capacitor-webview-guardian/?lang=original
项目主页：https://capgo.app/docs/plugins/
源码仓库：https://github.com/Cap-go/capacitor-webview-guardian

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

- 包体积（解压后）：77 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-10T00:24:28.905Z
- 最新版本发布：2026-10-19T12:33:44.150Z
- 近 30 天下载量：43662（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

当 WebView 在背景中被杀死时检测到的电容插件, 并在前景上重新启动 .

## 安装

```sh
npm install @capgo/capacitor-webview-guardian
```

也可以使用：`pnpm add @capgo/capacitor-webview-guardian`、`yarn add @capgo/capacitor-webview-guardian`、`bun add @capgo/capacitor-webview-guardian`

## README

# @capgo/capor-webview-守护者

当操作系统在背景中杀死了它的 WebView 时, 将您的 Capacitor app 带回生命: Webview Guardian 在前景上检查渲染器并自动重新装入.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-webview-guardian)](https://capgo.app/?ref=plugin_webview_guardian)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_webview_guardian)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_webview_guardian) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-webview-guardian` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-webview-guardian到我的Capacitor应用上并把它接上"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_webview_guardian) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_webview_guardian)

![@capgo/capacitor-webview-guardian for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-webview-guardian/main/assets/github-social-preview.png)

## 主要特点

-   **监测**数字 : `startMonitoring()` 财务报告和审定财务报表 `stopMonitoring()` 监视前景事件.
-   **自动重启**: 重新装入终止的 WebView 以 a `reload`, (中文(简体) ), `reloadFromOrigin` 或者说 `customUrl` 战略.
-   **卫生调查**数字 : `checkNow()` 立即测试Webview.
-   **状况和活动**数字 : `getState()` 编辑 `foreground` 活动.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 在网上不可用.

在操作系统杀死其WebView后,当该应用处于后台时,保持您的Capacitor应用活性. Webview Guardian聆听了前景事件,探测了渲染器,并在渲染过程终止后自动地重新加载(或通知您以便您恢复自己的状态).

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-webview-guardian` plugin in my project.
```

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

```bash
npm install @capgo/capacitor-webview-guardian
npx cap sync
```

## 使用量

```ts
import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

await WebviewGuardian.startMonitoring({
  foregroundDebounceMs: 800,
  autoRestart: true,
  restartStrategy: 'reload',
});

WebviewGuardian.addListener('webviewRestarted', ({ reason }) => {
  console.info('[guardian] WebView restarted', reason);
});
```

## API 密码

-   [`startMonitoring(...)`](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-startmonitoring)
-   [`stopMonitoring()`](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-stopmonitoring)
-   [`getState()`](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-getstate)
-   [`checkNow(...)`](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-checknow)
-   [`addListener('foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', ...)`](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-addlistenerforeground--webviewhealthy--webviewcrashed--webviewrestarted-)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-type-aliases)

### 启动监测(...)

```typescript
startMonitoring(options?: StartMonitoringOptions | undefined) => Promise<GuardianState>
```

开始观察前景事件,并自动检查WebView的健康.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartMonitoringOptions](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-startmonitoringoptions)` |

**回返情况:** `Promise<[GuardianState](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-guardianstate)>`

* * *

### 停止监视 ()

```typescript
stopMonitoring() => Promise<GuardianState>
```

停止任何自动前台监控.

**回返情况:** `Promise<[GuardianState](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-guardianstate)>`

* * *

### 获取状态( C)

```typescript
getState() => Promise<GuardianState>
```

返回最新已知的监测状态.

**回返情况:** `Promise<[GuardianState](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-guardianstate)>`

* * *

### 检查现在(...)

```typescript
checkNow(options?: CheckNowOptions | undefined) => Promise<CheckResult>
```

立即启动WebView健康探测器.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CheckNowOptions](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-checknowoptions)` |

**回返情况:** `Promise<[CheckResult](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-checkresult)>`

* * *

### 添加倾听器( “ 前景 ” QQ“ 网络视图健康 ” ) 。 )

```typescript
addListener(eventName: 'foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted', listenerFunc: (event: GuardianEvent) => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'foreground' | 'webviewHealthy' | 'webviewCrashed' | 'webviewRestarted'` |
| **`listenerFunc`** | `(event: [GuardianState](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-guardianstate)) => void` |

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

* * *

### 接口

#### 守护国

| Prop | 类型 |
| --- | --- |
| **`monitoring`** | `boolean` |
| **`reason`** | `string` |
| **`timestamp`** | `string` |
| **`lastHealthyAt`** | `string` |
| **`lastRestartAt`** | `string` |
| **`lastCrashAt`** | `string` |
| **`pendingRestartReason`** | `string` |
| **`error`** | `string` |

#### 开始监视选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`foregroundDebounceMs`** | `number` | 在应用程序重新进入前景后进行健康检查之前, 延迟( ms) 。 默认为600ms让大桥完成恢复. |
| **`pingScript`** | `string` | 脚本通过 `evaluateJavascript`编号 :`evaluateJavaScript` 以确认WebView还活着。 默认为 `document.readyState`。 。 。 . |
| **`autoRestart`** | `boolean` | 当检测到终止的渲染过程时, 自动重新装入 WebView 。 禁用以接收 `webviewCrashed` 事件并手动重新启动. |
| **`restartStrategy`** | `[RestartStrategy](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-restartstrategy)` | 重新启动 WebView 时使用的战略 。 默认为 `reload`。 。 。 . |
| **`customRestartUrl`** | `string` | 自定义 HTTPS/ HTTP URL 装入时 `restartStrategy` 实值 `customUrl`。 。 。 . |
| **`debug`** | `boolean` | 真实时在原生地层输入动词记录 . |
| **`runInitialCheck`** | `boolean` | 是否应当在允许监测后立即进行健康检查。 默认为 `true`。 。 。 . |

#### 检查结果

| Prop | 类型 |
| --- | --- |
| **`healthy`** | `boolean` |
| **`restarted`** | `boolean` |
| **`reason`** | `string` |
| **`timestamp`** | `string` |
| **`error`** | `string` |
| **`pendingRestart`** | `boolean` |

#### 检查当前选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`reason`** | `string` | 描述为什么需要手动检查的文本标签 . |

#### 插件听筒

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

### 类型异名

#### 重新启动战略

`'reload' | 'reloadFromOrigin' | 'customUrl'`

#### 守护事件

`[GuardianState](https://npmcn.com/package/%40capgo/capacitor-webview-guardian/#readme-guardianstate)`

## 常见问题

### @capgo/capacitor-webview-guardian 是什么？

当 WebView 在背景中被杀死时检测到的电容插件, 并在前景上重新启动 \.

### 如何安装 @capgo/capacitor-webview-guardian？

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

### @capgo/capacitor-webview-guardian 支持 TypeScript 吗？

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

### @capgo/capacitor-webview-guardian 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-webview-guardian 可以商用吗？

@capgo/capacitor-webview-guardian 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-webview-guardian 的下载量有多少？

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

### @capgo/capacitor-webview-guardian 还在维护吗？

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