Skip to main content

crashReporter

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

进程：主进程、渲染器

🌐 Process: Main, Renderer

info

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

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

🌐 The following is an example of setting up Electron to automatically submit crash reports to a remote server:

const { crashReporter } = require('electron')

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

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

🌐 For setting up a server to accept and process crash reports, you can use following projects:

note

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

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

🌐 Or use a 3rd party hosted solution:

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

🌐 Crash reports are stored temporarily before being uploaded in a directory underneath the app's user data directory, called 'Crashpad'. You can override this directory by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter.

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

🌐 Electron uses crashpad to monitor and report crashes.

方法​

🌐 Methods

crashReporter 模块具有以下方法：

🌐 The crashReporter module has the following methods:

crashReporter.start(options)​

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

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

🌐 This method must be called before using any other crashReporter APIs. Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. The crash reporter cannot be disabled once started.

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

🌐 This method should be called as early as possible in app startup, preferably before app.on('ready'). If the crash reporter is not initialized at the time a renderer process is created, then that renderer process will not be monitored by the crash reporter.

note

你可以通过使用 process.crash() 生成崩溃来测试崩溃报告器。

note

如果在第一次调用 start 之后需要发送额外的或更新的 extra 参数，可以调用 addExtraParameter。

note

通过 extra、globalExtra 传入或通过 addExtraParameter 设置的参数，其键和值的长度都有一定限制。键名最多为 39 个字节，值最长不能超过 127 个字节。超过最大长度的键名将被静默忽略。超过最大长度的键值将被截断。

note

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

crashReporter.getLastCrashReport()​

返回 CrashReport | null - 最近一次崩溃报告的日期和 ID。仅会返回已上传的崩溃报告；即使崩溃报告存在于磁盘上，也不会返回，直到它被上传。如果没有已上传的报告，则返回 null。

🌐 Returns CrashReport | null - The date and ID of the last crash report. Only crash reports that have been uploaded will be returned; even if a crash report is present on disk it will not be returned until it is uploaded. In the case that there are no uploaded reports, null is returned.

note

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

crashReporter.getUploadedReports()​

返回 CrashReport[]：

🌐 Returns CrashReport[]:

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

🌐 Returns all uploaded crash reports. Each report contains the date and uploaded ID.

note

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

crashReporter.getUploadToServer()​

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

🌐 Returns boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.

note

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

crashReporter.setUploadToServer(uploadToServer)​

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

这通常由用户偏好控制。如果在调用 start 之前调用，则不会生效。

🌐 This would normally be controlled by user preferences. This has no effect if called before start is called.

note

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

crashReporter.addExtraParameter(key, value)​

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

设置一个额外参数随崩溃报告发送。这里指定的值将会在调用 start 时，除了通过 extra 选项设置的任何值之外一并发送。

🌐 Set an extra parameter to be sent with the crash report. The values specified here will be sent in addition to any values set via the extra option when start was called.

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

🌐 Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. Adding extra parameters in the main process will not cause those parameters to be sent along with crashes from renderer or other child processes. Similarly, adding extra parameters in a renderer process will not result in those parameters being sent with crashes that occur in other renderer processes or in the main process.

note

参数对键和值的长度有一定限制。键名不能超过39字节，值不能超过20320字节。键名超过最大长度的将被静默忽略。键值超过最大长度的将被截断。

crashReporter.removeExtraParameter(key)​

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

从当前参数集中移除一个多余的参数。将来的崩溃中不会包含此参数。

🌐 Remove an extra parameter from the current set of parameters. Future crashes will not include this parameter.

crashReporter.getParameters()​

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

🌐 Returns Record<string, string> - The current 'extra' parameters of the crash reporter.

在 Node 子进程中​

🌐 In Node child processes

由于 require('electron') 在 Node 子进程中不可用，因此在 Node 子进程中可以通过 process 对象使用以下 API。

🌐 Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes.

process.crashReporter.start(options)​

请参见 crashReporter.start()。

🌐 See crashReporter.start().

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

🌐 Note that if the crash reporter is started in the main process, it will automatically monitor child processes, so it should not be started in the child process. Only use this method if the main process does not initialize the crash reporter.

process.crashReporter.getParameters()​

请参见 crashReporter.getParameters()。

🌐 See crashReporter.getParameters().

process.crashReporter.addExtraParameter(key, value)​

请参见 crashReporter.addExtraParameter(key, value)。

🌐 See crashReporter.addExtraParameter(key, value).

process.crashReporter.removeExtraParameter(key)​

请参见 crashReporter.removeExtraParameter(key)。

🌐 See crashReporter.removeExtraParameter(key).

崩溃报告有效负载​

🌐 Crash Report Payload

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

🌐 The crash reporter will send the following data to the submitURL as a multipart/form-data POST:

  • 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 对象的所有一级属性。