开始入门

安装

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

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

然后使用以下提示:

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

如果您更喜欢手动设置，请通过运行以下命令安装插件并按照以下平台特定的说明进行操作：

npm install @capgo/capacitor-webview-crash
npx cap sync

导入

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

推荐恢复流程

尽早在应用启动时附加监听器，以便恢复的运行时可以在用户继续浏览之前反应：

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);
}

原生自动重启

设置重启选项在 capacitor.config.ts 这样，决定就留在原生code中，即使JavaScript运行时已经崩溃或尚未加载：

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打开： restartCron kiosk屏幕、控制室仪表板、仓库扫描器、POS终端、车队平板电脑和数字标牌。使用 0 3 * * * 墙时钟重启，如 reason: 'periodicRestart', then Android recreates the host activity and iOS rebuilds the Capacitor bridge view so a new WKWebView 然后Android重新创建宿主活动，而iOS重新构建code桥视图，因此从原生code创建一个新的

选择一个时间间隔或计划任务，产品可以容忍。 restartCron 支持 *, 列表、范围和步长。不要同时配置两个计划：本机初始化会在 restartCron 设置且 restartIntervalMs 大于 0时抛出致命配置错误。重启会创建一个新的 JavaScript 运行时，因此在使用激进计划前，请保存排队事件、未保存的表单状态和当前导航状态。

手动本机重启

当当前 JavaScript 运行时决定本机 WebView 应该被替换时调用：例如在内存密集型工作流或进入长时间无人看管会话之前： restartWebView() 复制到剪贴板

await WebViewCrash.restartWebView();

Copy to clipboard reason: 'manualRestart', 解决当前调用，然后要求本地 code 创建一个新的 WebView。 Android 重建了宿主活动。 iOS 重建了 Capacitor 桥视图，因此创建了一个新的 WKWebView is 创建了一个新的页面，而不是重新加载当前页面。

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 当平台提供它们时
• Android 存储崩溃元数据从 webViewWebContentProcessDidTerminate 并添加当前应用程序状态（可用时）。
• 手动和计划重启创建一个新的 WebView。Android 重建宿主活动； iOS 重建Capacitor 桥视图。
• 计划重启使用 reason: 'periodicRestart'; 手动重启使用 reason: 'manualRestart'.
• Web 不检测真实渲染器崩溃。Web 实现仅模拟本地存储的行为。

类型参考

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在上游发生变化时，请重新同步。

继续从开始指南

如果您正在使用 Getting Started 来规划原生媒体和界面行为，连接它与 使用 @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-视频播放器 了解 @capgo/capacitor-视频播放器 的实现细节。