crashReporter

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

进程：主进程，渲染进程

信息

如果想在启用了上下文隔离的渲染进程中调用此 API，请将 API 调用放在你的 preload 脚本中，并使用 expose 它，通过 contextBridge API。

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

const { crashReporter } = require('electron')

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

要设置一个服务器来接收和处理崩溃报告，你可以使用以下项目

• socorro
• mini-breakpad-server

注意

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

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

• Backtrace
• Sentry
• BugSplat
• Bugsnag

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

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

方法

crashReporter 模块具有以下方法

crashReporter.start(options)

• options Object
  • submitURL string (可选) - 崩溃报告将作为 POST 请求发送到的 URL。除非 uploadToServer 为 false，否则是必需的。
  • productName string (可选) - 默认值为 app.name。
  • companyName string (可选) 已弃用 - { globalExtra: { _companyName: ... } } 的已弃用别名。
  • uploadToServer boolean (可选) - 是否将崩溃报告发送到服务器。如果为 false，崩溃报告将被收集并存储在崩溃目录中，但不会上传。默认值为 true。
  • ignoreSystemCrashHandler boolean (可选) - 如果为 true，在主进程中生成的崩溃将不会转发到系统崩溃处理程序。默认值为 false。
  • rateLimit boolean (可选) macOS Windows - 如果为 true，将上传的崩溃数量限制为每小时 1 次。默认值为 false。
  • compress boolean (可选) - 如果为 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 boolean - 是否应该将报告提交到服务器。

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

注意

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

crashReporter.addExtraParameter(key, value)

• key string - 参数键，最大长度为 39 个字节。
• value string - 参数值，最大长度为 127 个字节。

设置要与崩溃报告一起发送的额外参数。此处指定的值将与在调用 start 时 extra 选项中设置的值一起发送。

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

注意

参数的键和值的长度有限制。键名称的最大长度为 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 对象的全部一级属性。