跳转到正文

快速入门

GitHub

你可以使用我们的 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);
import { WebViewCrash } from '@capgo/capacitor-webview-crash';
await WebViewCrash.clearPendingCrashInfo();
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);
}

在 capacitor.config.ts 中设置重启选项,这样即使 JavaScript 运行时已崩溃或尚未加载,决策逻辑仍保留在原生 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 打开的常驻应用:Kiosk 屏幕、控制室仪表盘、仓库扫描仪、POS 终端、车队平板和数字标牌。使用 restartCron 用于基于墙钟时间的重启,例如 0 3 * * * 用于在设备本地时区每天 03:00 重启。计划重启会写入一个带有 reason: 'periodicRestart'的待处理标记,随后 Android 会重建宿主 Activity,iOS 会重建 Capacitor 桥接视图,从而创建一个新的 WKWebView ,由原生 code 初始化。

请选择您的产品能够容忍的时间间隔或 cron 计划。 restartCron 支持 *、列表、范围和步长。请勿同时配置两种计划:当 restartCron 已设置且 restartIntervalMs 大于 0时,原生初始化会抛出致命配置错误。重启会创建全新的 JavaScript 运行时,因此在使用激进的计划之前,请持久化排队的事件、未保存的表单状态和当前导航状态。

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

await WebViewCrash.restartWebView();

该方法会写入一个待处理标记, reason: 'manualRestart',解析当前调用,然后请求原生 code 创建一个新的 WebView。Android 会重建宿主 Activity。iOS 会重建 Capacitor 桥接视图,以便新的 WKWebView 被创建,而不是重新加载当前页面。

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

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

恢复处理结束后清除已存储的标记。

await WebViewCrash.clearPendingCrashInfo();

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

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

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

await WebViewCrash.restartWebView();
  • Android 会存储崩溃元数据,来源为 onRenderProcessGone,包括 didCrash 以及 rendererPriorityAtExit 当平台提供这些信息时。
  • iOS 会存储来自 webViewWebContentProcessDidTerminate 并在可用时添加当前应用状态。
  • 手动和定时重启会创建一个全新的 WebView。Android 会重新创建宿主 Activity;iOS 则会重建 Capacitor 的 bridge 视图。
  • 定时重启使用 reason: 'periodicRestart';手动重启使用 reason: 'manualRestart'.
  • Web 端无法检测真实的渲染器崩溃。Web 实现仅用 localStorage 模拟该行为。
export interface PendingCrashInfoResult {
/**
* Stored crash or restart metadata, or `null` when no marker is pending.
*/
value: WebViewCrashInfo | null;
}
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;
}
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;
}
export type WebViewCrashPlatform = 'android' | 'ios' | 'web';
export type WebViewCrashReason =
| 'renderProcessGone'
| 'webContentProcessDidTerminate'
| 'periodicRestart'
| 'manualRestart'
| 'simulated';
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. 中的实现细节