跳至主要内容

crashReporter

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

进程：主进程，渲染进程

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

const { crashReporter } = require('electron')

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

要设置接受和处理崩溃报告的服务器，可以使用以下项目

注意：Electron 使用 Crashpad，而不是 Breakpad 来收集和上传崩溃，但目前，上传协议相同。

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

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

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

方法​

crashReporter 模块具有以下方法

crashReporter.start(options)​

  • options 对象
    • submitURL 字符串（可选） - 崩溃报告将作为 POST 发送到的 URL。除非 uploadToServer 为 false，否则为必填。
    • productName 字符串（可选） - 默认值为 app.name。
    • companyName 字符串（可选） 已弃用 - { globalExtra: { _companyName: ... } } 的已弃用别名。
    • uploadToServer 布尔值（可选） - 是否应将崩溃报告发送到服务器。如果为 false，则崩溃报告将被收集并存储在 crashes 目录中，但不会上传。默认为 true。
    • ignoreSystemCrashHandler 布尔值（可选） - 如果为 true，则主进程中生成的崩溃将不会转发到系统崩溃处理程序。默认为 false。
    • rateLimit 布尔值（可选） macOS Windows - 如果为 true，则将上传的崩溃次数限制为每小时 1 次。默认为 false。
    • compress 布尔值（可选） - 如果为 true，则崩溃报告将被压缩并使用 Content-Encoding: gzip 上传。默认为 true。
    • extra Record<string, string>（可选） - 将与在主进程中生成的崩溃报告一起发送的其他字符串键/值注释。仅支持字符串值。子进程中生成的崩溃将不包含这些其他参数，要发送到子进程中生成的崩溃报告，请从子进程中调用 addExtraParameter。
    • globalExtra Record<string, string>（可选） - 将与在任何进程中生成的任何崩溃报告一起发送的其他字符串键/值注释。一旦启动了崩溃报告程序，这些注释就不能更改。如果全局额外参数和特定于进程的额外参数中都存在某个键，则全局键将优先。默认情况下，会包含 productName 和应用程序版本，以及 Electron 版本。

必须在使用任何其他 crashReporter API 之前调用此方法。以这种方式初始化后，crashpad 处理程序会从随后创建的所有进程中收集崩溃。一旦启动，崩溃报告程序就无法禁用。

此方法应在应用程序启动时尽早调用，最好在 app.on('ready') 之前调用。如果在创建渲染器进程时未初始化崩溃报告程序，则该渲染器进程将不会受到崩溃报告程序的监视。

注意：您可以使用 process.crash() 生成崩溃来测试崩溃报告程序。

注意：如果需要在第一次调用 start 后发送其他/更新的 extra 参数，可以调用 addExtraParameter。

注意：通过 extra、globalExtra 传递或使用 addExtraParameter 设置的参数对键和值的长度有限制。键名最长为 39 个字节，值最长为 127 个字节。名称超过最大长度的键将被静默忽略。超过最大长度的键值将被截断。

注意：此方法仅在主进程中可用。

crashReporter.getLastCrashReport()​

返回 CrashReport | null - 上次崩溃报告的日期和 ID。仅返回已上传的崩溃报告；即使崩溃报告存在于磁盘上，也必须上传后才会返回。如果没有任何上传的报告，则返回 null。

注意：此方法仅在主进程中可用。

crashReporter.getUploadedReports()​

返回 CrashReport[]

返回所有已上传的崩溃报告。每个报告都包含日期和上传的 ID。

注意：此方法仅在主进程中可用。

crashReporter.getUploadToServer()​

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

注意：此方法仅在主进程中可用。

crashReporter.setUploadToServer(uploadToServer)​

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

这通常由用户偏好控制。如果在调用 start 之前调用，则此方法无效。

注意：此方法仅在主进程中可用。

crashReporter.addExtraParameter(key, value)​

  • key 字符串 - 参数键，不得超过 39 个字节。
  • value 字符串 - 参数值，不得超过 127 个字节。

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

以这种方式（或通过 crashReporter.start 的 extra 参数）添加的参数特定于调用进程。在主进程中添加其他参数不会导致这些参数与来自渲染器或其他子进程的崩溃一起发送。同样，在渲染器进程中添加其他参数不会导致这些参数与在其他渲染器进程或主进程中发生的崩溃一起发送。

注意：参数对键和值的长度有限制。键名最长为 39 个字节，值最长为 20320 个字节。名称超过最大长度的键将被静默忽略。超过最大长度的键值将被截断。

crashReporter.removeExtraParameter(key)​

  • key 字符串 - 参数键，不得超过 39 个字节。

从当前参数集中删除其他参数。将来的崩溃将不包含此参数。

crashReporter.getParameters()​

返回 Record<string, string> - 崩溃报告程序的当前“额外”参数。

在 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 字符串 - Electron 的版本。
  • platform 字符串 - 例如 'win32'。
  • process_type 字符串 - 例如 'renderer'。
  • guid 字符串 - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72'。
  • _version 字符串 - package.json 中的版本。
  • _productName 字符串 - crashReporter 的 options 对象中的产品名称。
  • prod 字符串 - 底层产品的名称。在本例中为 Electron。
  • _companyName 字符串 - crashReporter 的 options 对象中的公司名称。
  • upload_file_minidump 文件 - minidump 格式的崩溃报告。
  • crashReporter 的 options 对象中 extra 对象的所有一级属性。