crashReporter

Submit crash reports to a remote server.将崩溃报告提交到远程服务器。

Process: 进程：Main, Renderer

The following is an example of setting up Electron to automatically submit crash reports to a remote server:以下是设置Electron以自动向远程服务器提交故障报告的示例：

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:要设置服务器以接受和处理崩溃报告，可以使用以下项目：

• socorro
• mini-breakpad-server

Note: Electron uses Crashpad, not Breakpad, to collect and upload crashes, but for the time being, the upload protocol is the same.Electron使用Crashpad而不是Breakpad来收集和上传崩溃，但目前上传协议是一样的。

Or use a 3rd party hosted solution:或者使用第三方托管的解决方案：

• Backtrace
• Sentry
• BugSplat
• Bugsnag

Crash reports are stored temporarily before being uploaded in a directory underneath the app's user data directory, called 'Crashpad'. 崩溃报告在上传到应用程序用户数据目录下的一个名为“Crashpad”的目录之前会被临时存储。You can override this directory by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter.在启动崩溃报告程序之前，您可以通过调用app.setPath('crashDumps', '/path/to/crashes')来覆盖此目录。

Electron uses crashpad to monitor and report crashes.Electron使用crashpad来监控和报告崩溃。

Methods方法

The crashReporter module has the following methods:crashReporter模块具有以下方法：

crashReporter.start(options)

• options Object
  • submitURL string (optional) - URL that crash reports will be sent to as POST. 崩溃报告将作为POST发送到的URL。Required unless uploadToServer is false.除非uploadToServer为false，否则为必需。
  • productName string (optional) - Defaults to app.name.默认为app.name。
  • companyName string (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.{ globalExtra: { _companyName: ... } }的别名已弃用。
  • uploadToServer boolean (optional) - Whether crash reports should be sent to the server. 是否应将崩溃报告发送到服务器。If false, crash reports will be collected and stored in the crashes directory, but not uploaded. 如果为false，则崩溃报告将被收集并存储在崩溃目录中，但不会上传。Default is true.默认值为true。
  • ignoreSystemCrashHandler boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. 如果为true，则主进程中生成的崩溃将不会转发到系统崩溃处理程序。Default is false.默认值为false。
  • rateLimit boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. 如果为true，则将上传的崩溃次数限制为1次/小时。Default is false.默认值为false。
  • compress boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. 如果为true，则崩溃报告将被压缩并使用Content-Encoding: gzip上传。Default is true.默认值为true。
  • extra Record<string, string> (optional) - Extra string key/value annotations that will be sent along with crash reports that are generated in the main process. 额外的字符串键/值注释将与主进程中生成的崩溃报告一起发送。Only string values are supported. 仅支持字符串值。Crashes generated in child processes will not contain these extra parameters to crash reports generated from child processes, call addExtraParameter from the child process.在子进程中生成的崩溃将不包含这些额外的参数。要从子进程生成的崩溃报告，请从子进程调用addExtraParameter。
  • globalExtra Record<string, string> (optional) - Extra string key/value annotations that will be sent along with any crash reports generated in any process. 额外的字符串键/值注释将与任何进程中生成的任何崩溃报告一起发送。These annotations cannot be changed once the crash reporter has been started. 一旦启动崩溃报告程序，就无法更改这些注释。If a key is present in both the global extra parameters and the process-specific extra parameters, then the global one will take precedence. 如果全局额外参数和进程特定额外参数中都存在键，则全局键将优先。By default, productName and the app version are included, as well as the Electron version.默认情况下，包括productName和应用程序版本，以及Electron版本。

This method must be called before using any other crashReporter APIs. 在使用任何其他crashReporter API之前，必须调用此方法。Once initialized this way, the crashpad handler collects crashes from all subsequently created processes. 一旦以这种方式初始化，crashpad处理程序就会从所有随后创建的进程中收集崩溃。The crash reporter cannot be disabled once started.崩溃报告程序一旦启动就无法禁用。

This method should be called as early as possible in app startup, preferably before app.on('ready'). 此方法应在应用程序启动时尽早调用，最好在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: You can test out the crash reporter by generating a crash using process.crash().您可以通过使用process.crash()生成崩溃来测试崩溃报告程序。

Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.如果您需要在第一次调用start后发送额外/更新的extra参数，您可以调用addExtraParameter。

Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. 传入extra、globalExtra或使用addExtraParameter设置的参数对键和值的长度有限制。Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. 密钥名称的长度最多不得超过39个字节，值的长度不得超过127个字节。Keys with names longer than the maximum will be silently ignored. 名称超过最大值的键将被忽略。Key values longer than the maximum length will be truncated.超过最大长度的键值将被截断。

Note: This method is only available in the main process.此方法仅在主进程中可用。

crashReporter.getLastCrashReport()

Returns 返回CrashReport - The date and ID of the last crash report. 上次崩溃报告的日期和ID。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.如果没有上传的报告，则返回null。

Note: This method is only available in the main process.此方法仅在主进程中可用。

crashReporter.getUploadedReports()

Returns 返回CrashReport[]:

Returns all uploaded crash reports. 返回所有上传的崩溃报告。Each report contains the date and uploaded ID.每个报告都包含日期和上传的ID。

Note: This method is only available in the main process.此方法仅在主进程中可用。

crashReporter.getUploadToServer()

Returns 返回boolean - Whether reports should be submitted to the server. 是否应将报告提交到服务器。Set through the start method or setUploadToServer.通过start方法或setUploadToServer进行设置。

Note: This method is only available in the main process.此方法仅在主进程中可用。

crashReporter.setUploadToServer(uploadToServer)

• uploadToServer boolean - Whether reports should be submitted to the server.是否应将报告提交到服务器。

This would normally be controlled by user preferences. 这通常由用户偏好控制。This has no effect if called before start is called.如果在调用start之前调用，则此操作无效。

Note: This method is only available in the main process.此方法仅在主进程中可用。

crashReporter.addExtraParameter(key, value)

• key string - Parameter key, must be no longer than 39 bytes.参数键的长度不得超过39个字节。
• value string - Parameter value, must be no longer than 127 bytes.参数值的长度不得超过127个字节。

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.调用start时，除了通过extra选项设置的任何值之外，还会发送此处指定的值。

Parameters added in this fashion (or via the extra parameter to crashReporter.start) are specific to the calling process. 以这种方式（或通过crashReporter.start的extra参数）添加的参数是特定于调用进程的。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: Parameters have limits on the length of the keys and values. 参数对键和值的长度有限制。Key names must be no longer than 39 bytes, and values must be no longer than 20320 bytes. 密钥名称不得超过39个字节，值不得超过20320个字节。Keys with names longer than the maximum will be silently ignored. 名称超过最大值的键将被忽略。Key values longer than the maximum length will be truncated.超过最大长度的键值将被截断。

crashReporter.removeExtraParameter(key)

• key string - Parameter key, must be no longer than 39 bytes.参数键的长度不得超过39个字节。

Remove an extra parameter from the current set of parameters. 从当前参数集中删除一个额外的参数。Future crashes will not include this parameter.未来的崩溃将不包括此参数。

crashReporter.getParameters()

Returns 返回Record<string, string> - The current 'extra' parameters of the crash reporter.崩溃报告程序的当前“额外”参数。

In Node child processes节点内子进程

Since require('electron') is not available in Node child processes, the following APIs are available on the process object in Node child processes.由于require('electron')在Node子进程中不可用，因此以下API可用于Node子进程的进程对象。

process.crashReporter.start(options)

See crashReporter.start().请参阅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()

See crashReporter.getParameters().请参阅crashReporter.getParameters()。

process.crashReporter.addExtraParameter(key, value)

See crashReporter.addExtraParameter(key, value).请参阅crashReporter.addExtraParameter(key, value)。

process.crashReporter.removeExtraParameter(key)

See crashReporter.removeExtraParameter(key).请参阅crashReporter.removeExtraParameter(key)。

Crash Report Payload碰撞报告有效载荷

The crash reporter will send the following data to the submitURL as a multipart/form-data POST:崩溃报告程序将以下数据作为multipart/form-data POST发送到submitURL：

• ver string - The version of Electron.Electron的版本号。
• platform string - e.g. 'win32'.例如'win32'。
• process_type string - e.g. 'renderer'.例如'renderer'。
• guid string - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'.例如'5e1286fc-da97-479e-918b-6bfb0c3d1c72'。
• _version string - The version in package.json.package.json中的版本号。
• _productName string - The product name in the crashReporter options object.crashReporter options对象中的产品名称。
• prod string - Name of the underlying product. 基础产品的名称。In this case Electron.在这种情况下是Electron。
• _companyName string - The company name in the crashReporter options object.crashReporter options对象中的公司名称。
• upload_file_minidump File - The crash report in the format of minidump.minidump格式的崩溃报告。
• All level one properties of the extra object in the crashReporter options object.crashReporter options对象中extra对象的所有一级属性。