快速入门
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-webview-crash`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/webview-crash/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
安装
“安装”章节你可以使用我们的 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-crashbunx 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
标题为“示例:clearPendingCrashInfo”的章节import { WebViewCrash } from '@capgo/capacitor-webview-crash';
await WebViewCrash.clearPendingCrashInfo();示例:simulateCrashRecovery
标题为“示例: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);}原生自动重启
标题为“原生自动重启”的章节在 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 被创建,而不是重新加载当前页面。
API 概览
标题为“API 概览”的章节getPendingCrashInfo
标题为“getPendingCrashInfo”的章节返回已存储的原生崩溃或重启标记,或 null 当没有待处理项时。
const pending = await WebViewCrash.getPendingCrashInfo();if (pending.value) { console.log(pending.value.platform, pending.value.reason);}clearPendingCrashInfo
“clearPendingCrashInfo” 章节恢复处理结束后清除已存储的标记。
await WebViewCrash.clearPendingCrashInfo();simulateCrashRecovery
“simulateCrashRecovery” 章节创建一个模拟崩溃标记,以便 QA 和本地调试可以在不导致真实 WebView 崩溃的情况下测试恢复流程。
const simulated = await WebViewCrash.simulateCrashRecovery();console.log(simulated.value);restartWebView
“restartWebView” 章节存储手动重启标记,并请求原生 code 创建一个全新的 WebView。
await WebViewCrash.restartWebView();平台说明
“平台说明” 章节- Android 会存储崩溃元数据,来源为
onRenderProcessGone,包括didCrash以及rendererPriorityAtExit当平台提供这些信息时。 - iOS 会存储来自
webViewWebContentProcessDidTerminate并在可用时添加当前应用状态。 - 手动和定时重启会创建一个全新的 WebView。Android 会重新创建宿主 Activity;iOS 则会重建 Capacitor 的 bridge 视图。
- 定时重启使用
reason: 'periodicRestart';手动重启使用reason: 'manualRestart'. - Web 端无法检测真实的渲染器崩溃。Web 实现仅用 localStorage 模拟该行为。
类型参考
标题为“类型参考”的章节PendingCrashInfoResult
标题为“PendingCrashInfoResult”的章节export interface PendingCrashInfoResult { /** * Stored crash or restart metadata, or `null` when no marker is pending. */ value: WebViewCrashInfo | null;}WebViewCrashPluginConfig
“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
“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
“WebViewCrashPlatform” 章节export type WebViewCrashPlatform = 'android' | 'ios' | 'web';WebViewCrashReason
“WebViewCrashReason” 章节export type WebViewCrashReason = | 'renderProcessGone' | 'webContentProcessDidTerminate' | 'periodicRestart' | 'manualRestart' | 'simulated';WebViewCrashAppState
“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. 中的实现细节