crashReporter¶

将崩溃报告提交到远程服务器。

进程：主进程, 渲染进程

[!IMPORTANT] 如果要在启用上下文隔离的渲染进程中调用此 API， 请将 API 调用放在 preload 脚本中，并使用 contextBridge API 将其暴露。

以下是配置 Electron 自动将崩溃报告提交到远程服务器的示例：

const { crashReporter } = require('electron')

crashReporter.start({ submitURL: 'https://your-domain.com/url-to-submit' })

若要配置用于接收和处理崩溃报告的服务器，可以使用以下项目：

• socorro
• mini-breakpad-server

[!NOTE] Electron 使用 Crashpad 而非 Breakpad 来收集和上传崩溃，但就目前而言，上传协议是相同的。

或使用第三方托管解决方案：

• Backtrace
• Sentry
• BugSplat
• Bugsnag

崩溃报告在上传前会临时存储在应用用户数据目录下的一个名为 'Crashpad' 的目录中。你可以通过在启动崩溃报告器之前调用 app.setPath('crashDumps', '/path/to/crashes') 来覆盖此目录。

Electron 使用 crashpad 来监控和报告崩溃。

在 Windows 上，某些崩溃永远无法到达进程内崩溃处理程序，最典型的是 __fastfail 终止（STATUS_STACK_BUFFER_OVERRUN，由安全检查失败、控制流保护违规以及 C 运行时的 abort() 引发）。为了捕获这些崩溃，Electron 附带了 electron_wer.dll，这是一个 Windows 错误报告（WER）运行时异常辅助程序，Windows（10 20H1 及更高版本）会在发生此类崩溃后以进程外方式加载它，并要求 crashpad 处理程序写入 minidump。当调用 crashReporter.start() 时，Electron 会将该 DLL 列在 HKEY_CURRENT_USER\Software\Microsoft\Windows\Windows Error Reporting\RuntimeExceptionHelperModules 下，这是 Windows 在加载辅助程序之前所要求的，并将其注册到每个 Electron 进程。辅助程序会在可执行文件旁边按 <executable name>_wer.dll 查找，因此如果你在打包时将 electron.exe 重命名为 myapp.exe，也要将 electron_wer.dll 重命名为 myapp_wer.dll。写入 HKEY_LOCAL_MACHINE 的安装程序可能会将其列在那里。若要退出，请勿附带该 DLL。

方法¶

crashReporter 模块具有以下方法：

crashReporter.start(options)¶

返回 CrashReport | null - 最后一次崩溃报告的日期和 ID。只有已上传的崩溃报告才会被返回；即使磁盘上存在崩溃报告，在上传之前也不会被返回。如果没有已上传的报告，则返回 null。

[!NOTE] 此方法仅在主进程中可用。

crashReporter.getUploadedReports()¶

返回 boolean - 是否应将报告提交到服务器。通过 start 方法或 setUploadToServer 设置。

[!NOTE] 此方法仅在主进程中可用。

crashReporter.setUploadToServer(uploadToServer)¶

• uploadToServer boolean - 是否应将报告提交到服务器。

这通常由用户偏好设置控制。如果在调用 start 之前调用，则没有效果。

[!NOTE] 此方法仅在主进程中可用。

crashReporter.addExtraParameter(key, value)¶

• key string - 参数键，长度不得超过 39 字节。
• value string - 参数值，长度不得超过 127 字节。

设置一个随崩溃报告一起发送的额外参数。此处指定的值将与调用 start 时通过 extra 选项设置的任何值一起发送。

以这种方式添加的参数（或通过 crashReporter.start 的 extra 参数添加）仅针对调用进程。在主进程中添加额外参数不会导致这些参数随渲染进程或其他子进程的崩溃一起发送。同样，在渲染进程中添加额外参数不会导致这些参数随其他渲染进程或主进程中发生的崩溃一起发送。

[!NOTE] 参数键和值的长度有限制。键名不得超过 39 字节，值不得超过 20320 字节。名称超过最大长度的键将被静默忽略。超过最大长度的键值将被截断。

crashReporter.removeExtraParameter(key)¶

• key string - 参数键，长度不得超过 39 字节。

从当前参数集中移除一个额外参数。未来的崩溃将不包含此参数。

crashReporter.getParameters()¶

返回 Record<string, string> - 崩溃报告器当前的 'extra' 参数。

在 Node 子进程中¶

由于 require('electron') 在 Node 子进程中不可用，以下 API 在 Node 子进程的 process 对象上可用。

process.crashReporter.start(options)¶

参见 crashReporter.start()。

请注意，如果在主进程中启动了崩溃报告器，它将自动监控子进程，因此不应在子进程中启动。仅当主进程未初始化崩溃报告器时，才使用此方法。

process.crashReporter.getParameters()¶

参见 crashReporter.getParameters()。

process.crashReporter.addExtraParameter(key, value)¶

参见 crashReporter.addExtraParameter(key, value)。

process.crashReporter.removeExtraParameter(key)¶

参见 crashReporter.removeExtraParameter(key)。

崩溃报告负载¶

崩溃报告器将以 multipart/form-data POST 的形式向 submitURL 发送以下数据：

• ver string - Electron 的版本。
• platform string - 例如 'win32'。
• process_type string - 例如 'renderer'。
• guid string - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72'。
• _version string - package.json 中的版本。
• _productName string - crashReporter options 对象中的产品名称。
• prod string - 底层产品的名称。在此情况下为 Electron。
• _companyName string - crashReporter options 对象中的公司名称。
• upload_file_minidump File - 格式为 minidump 的崩溃报告。
• crashReporter options 对象中 extra 对象的所有第一层属性。