快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

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

如果你更倾向于手动设置，请运行以下命令安装插件，并参考下文针对各平台的具体说明：

bun add @capgo/capacitor-webview-crash
bunx cap sync

导入

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

快速入门

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

const result = await WebViewCrash.getPendingCrashInfo();
console.log(result);

示例：clearPendingCrashInfo

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

await WebViewCrash.clearPendingCrashInfo();

示例：simulateCrashRecovery

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

const result = await WebViewCrash.simulateCrashRecovery();
console.log(result);

常见坑点

• 监听器: 在页面卸载时移除句柄。
• 原生同步: 运行 bunx cap sync 在插件升级后。
• 单一事实来源: 信任 src/definitions.ts 在 GitHub 仓库中。

推荐的恢复流程

请尽可能早地在应用启动时挂载监听器，以便在用户继续操作前，恢复后的运行时能够做出响应：

import { WebViewCrash } from '@capgo/capacitor-webview-crash';

await WebViewCrash.addListener('webViewRestoredAfterCrash', async (info) => {
  console.log('Recovered after a WebView crash', info);

  // Rehydrate critical state, reopen the correct screen, or prompt the user to retry.
  await WebViewCrash.clearPendingCrashInfo();
});

await WebViewCrash.addListener('webViewRestoredAfterRestart', async (info) => {
  console.log('Recovered after a native WebView restart', info);
  await WebViewCrash.clearPendingCrashInfo();
});

const pending = await WebViewCrash.getPendingCrashInfo();
// Note: the listener callback may have already cleared the pending marker.
if (pending.value) {
  console.log('Pending crash or restart marker', pending.value);
}

Native 自动重启

在以下位置设置重启选项： capacitor.config.ts 这样即使 JavaScript 运行时崩溃或尚未加载，决策逻辑仍保留在 native code 中：

import type { CapacitorConfig } from '@capacitor/cli';
import type { WebViewCrashPluginConfig } from '@capgo/capacitor-webview-crash';

const webViewCrash: WebViewCrashPluginConfig = {
  // Enabled by default. Keep this on for long-running apps.
  restartOnCrash: true,

  // Use a 5-field cron schedule in the device local timezone.
  // Do not combine restartCron with an active restartIntervalMs.
  restartCron: '0 3 * * *',

  // Optional delay before restarting after a crash.
  restartAfterCrashDelayMs: 0,
};

const config: CapacitorConfig = {
  plugins: {
    WebViewCrash: webViewCrash,
  },
};

export default config;

使用 restartIntervalMs 适用于用户可能连续几天保持同一个 WebView 开启的常驻应用：如自助终端、控制室 dashboard、仓库扫描枪、POS 终端、车队平板和数字标牌。请使用 restartCron 用于特定时间的重启，例如： 0 3 * * * 用于设备本地时区每天 03:00 的重启。计划重启会写入一个待处理标记，并带有 reason: 'periodicRestart'，随后 Android 会重新创建宿主 Activity，iOS 则会重建 Capacitor bridge view，从而创建一个新的 WKWebView ，该视图由原生 code 生成。

请选择您的产品可以接受的时间间隔或 cron 调度计划。 restartCron 支持 *、列表、范围和步长。请勿同时配置两种调度方式：当设置了 restartCron 且 restartIntervalMs 大于 0时，原生初始化会抛出致命配置错误。重启会创建一个全新的 JavaScript 运行时，因此在使用激进的调度计划前，请务必持久化队列中的事件、未保存的表单状态以及当前的导航状态。

手动 Native 重启

调用 restartWebView() 当当前的 JavaScript 运行时决定主动替换原生 WebView 时，例如在执行内存密集型工作流之后，或在进入长时间无人值守会话之前：

await WebViewCrash.restartWebView();

该方法会写入一个待处理标记，并 reason: 'manualRestart'，解析当前的调用，然后请求原生 code 创建一个新的 WebView。Android 会重新创建宿主 Activity。iOS 会重建 Capacitor bridge view，从而使新的 WKWebView ，而不是重新加载当前页面。

API 概览

getPendingCrashInfo

返回已存储的原生崩溃或重启标记，或 null 在没有待处理项时。

const pending = await WebViewCrash.getPendingCrashInfo();
if (pending.value) {
  console.log(pending.value.platform, pending.value.reason);
}

clearPendingCrashInfo

在恢复处理完成后清除已存储的标记。

await WebViewCrash.clearPendingCrashInfo();

simulateCrashRecovery

创建一个模拟崩溃标记，以便 QA 和本地调试可以在不导致真实 WebView 崩溃的情况下测试恢复流程。

const simulated = await WebViewCrash.simulateCrashRecovery();
console.log(simulated.value);

restartWebView

存储手动重启标记，并请求原生 code 创建一个新的 WebView。

await WebViewCrash.restartWebView();

平台说明

• Android 会存储来自 onRenderProcessGone，包括 didCrash 和 rendererPriorityAtExit 当平台提供这些信息时。
• iOS 会存储来自 webViewWebContentProcessDidTerminate 并在可用时添加当前应用状态。
• 手动和定时重启会创建一个全新的 WebView。Android 会重新创建宿主 Activity；iOS 则会重建 Capacitor bridge view。
• 定时重启使用 reason: 'periodicRestart'；手动重启使用 reason: 'manualRestart'.
• Web 端无法检测到真实的渲染器崩溃。Web 实现仅通过 local storage 模拟该行为。

输入 reference

PendingCrashInfoResult

export interface PendingCrashInfoResult {
  /**
   * Stored crash or restart metadata, or `null` when no marker is pending.
   */
  value: WebViewCrashInfo | null;
}

WebViewCrashPluginConfig

export interface WebViewCrashPluginConfig {
  /**
   * Restart the WebView from native code when the renderer process dies.
   *
   * @default true
   */
  restartOnCrash?: boolean;

  /**
   * Fixed native interval, in milliseconds, for proactively replacing long-running WebViews.
   *
   * Set to `0` to disable interval restarts. Do not combine an active interval
   * with `restartCron`; native initialization fails fast when both schedules are configured.
   *
   * @default 0
   */
  restartIntervalMs?: number;

  /**
   * Cron schedule for proactively replacing long-running WebViews.
   *
   * Uses standard 5-field cron syntax in the device local timezone:
   * `minute hour day-of-month month day-of-week`.
   *
   * Examples:
   * - `0 3 * * *` restarts every day at 03:00.
   * - `0,30 * * * *` restarts every 30 minutes.
   *
   * Do not combine this with an active `restartIntervalMs`; native initialization
   * fails fast when both schedules are configured.
   */
  restartCron?: string;

  /**
   * Delay, in milliseconds, before restarting after a crash.
   *
   * @default 0
   */
  restartAfterCrashDelayMs?: number;
}

WebViewCrashInfo

export interface WebViewCrashInfo {
  /**
   * Platform that detected and stored the marker.
   */
  platform: WebViewCrashPlatform;

  /**
   * Unix timestamp in milliseconds for when the marker was written.
   */
  timestamp: number;

  /**
   * ISO-8601 version of `timestamp`.
   */
  timestampISO: string;

  /**
   * Platform-specific reason for the crash or restart marker.
   */
  reason: WebViewCrashReason;

  /**
   * Last known WebView URL when the marker was written.
   */
  url?: string;

  /**
   * Android-only hint from `RenderProcessGoneDetail.didCrash()`.
   */
  didCrash?: boolean;

  /**
   * Android-only renderer priority reported at exit.
   */
  rendererPriorityAtExit?: number;

  /**
   * iOS-only application state captured when the WebView process died.
   */
  appState?: WebViewCrashAppState;
}

WebViewCrashPlatform

export type WebViewCrashPlatform = 'android' | 'ios' | 'web';

WebViewCrashReason

export type WebViewCrashReason =
  | 'renderProcessGone'
  | 'webContentProcessDidTerminate'
  | 'periodicRestart'
  | 'manualRestart'
  | 'simulated';

WebViewCrashAppState

export type WebViewCrashAppState = 'active' | 'inactive' | 'background' | 'unknown';

唯一数据源

本页面由该插件的 src/definitions.ts当上游的公共 API 发生变化时，请重新运行 sync。

继续阅读入门指南

如果你正在使用 快速入门 来规划原生媒体和界面行为，并将其与 使用 @capgo/capacitor-webview-crash 关于“使用 @capgo/capacitor-webview-crash”中的原生能力， 使用 @capgo/capacitor-live-activities 有关“使用 @capgo/capacitor-live-activities”中的原生能力， @capgo/capacitor-live-activities 关于 @capgo/capacitor-live-activities 的实现细节， 使用 @capgo/capacitor-video-player 用于“使用 @capgo/capacitor-video-player”中的原生能力，以及 @capgo/capacitor-video-player 有关 @capgo/capacitor-video-player. 中的实现细节