crashReporter

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

¥Submit crash reports to a remote server.

进程：主进程、渲染器

¥Process: Main, Renderer

以下是设置 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:

• socorro

• mini-breakpad-server

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

¥Note: Electron uses Crashpad, not Breakpad, to collect and upload crashes, but for the time being, the upload protocol is the same.

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

¥Or use a 3rd party hosted solution:

• 回溯

  ¥Backtrace

• Sentry

• BugSplat

• 虫子

  ¥Bugsnag

崩溃报告在上传到应用用户数据目录下的目录（名为 '崩溃垫'）之前会暂时存储。你可以在启动崩溃报告器之前调用 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 对象

  ¥options Object

  • submitURL 字符串（可选） - 崩溃报告将以 POST 形式发送到的 URL。必需的，除非 uploadToServer 是 false。

    ¥submitURL string (optional) - URL that crash reports will be sent to as POST. Required unless uploadToServer is false.

  • productName 字符串（可选） - 默认为 app.name。

    ¥productName string (optional) - Defaults to app.name.

  • companyName 字符串（可选）已弃用 - 已弃用 { globalExtra: { _companyName: ... } } 的别名。

    ¥companyName string (optional) Deprecated - Deprecated alias for { globalExtra: { _companyName: ... } }.

  • uploadToServer 布尔值（可选） - 是否应将崩溃报告发送到服务器。如果为 false，崩溃报告将被收集并存储在 crashes 目录中，但不会上传。默认为 true。

    ¥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. Default is true.

  • ignoreSystemCrashHandler 布尔值（可选） - 如果为 true，则主进程中生成的崩溃将不会转发到系统崩溃处理程序。默认为 false。

    ¥ignoreSystemCrashHandler boolean (optional) - If true, crashes generated in the main process will not be forwarded to the system crash handler. Default is false.

  • rateLimit 布尔值（可选） macOS Windows - 如果为 true，则将上传的崩溃次数限制为 1/小时。默认为 false。

    ¥rateLimit boolean (optional) macOS Windows - If true, limit the number of crashes uploaded to 1/hour. Default is false.

  • compress 布尔值（可选） - 如果为真，崩溃报告将被压缩并使用 Content-Encoding: gzip 上传。默认为 true。

    ¥compress boolean (optional) - If true, crash reports will be compressed and uploaded with Content-Encoding: gzip. Default is true.

  • extra Record<string, string> (optional) - 额外的字符串键/值注释将与主进程中生成的崩溃报告一起发送。仅支持字符串值。子进程中生成的崩溃不会包含这些额外的参数，从子进程生成的崩溃报告中，从子进程中调用 addExtraParameter。

    ¥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.

  • globalExtra Record<string, string> (optional) - 额外的字符串键/值注释将与任何进程中生成的任何崩溃报告一起发送。一旦崩溃报告器启动，这些注释就无法更改。如果全局额外参数和特定于进程的额外参数中都存在某个键，则全局额外参数优先。默认情况下，包括 productName 和应用版本，以及 Electron 版本。

    ¥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.

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

¥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.

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

¥Note: You can test out the crash reporter by generating a crash using process.crash().

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

¥Note: If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.

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

¥Note: Parameters passed in extra, globalExtra or set with addExtraParameter have limits on the length of the keys and values. Key names must be at most 39 bytes long, and values must be no longer than 127 bytes. 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()

返回 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: This method is only available in the main process.

crashReporter.getUploadedReports()

返回 CrashReport[]：

¥Returns CrashReport[]:

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

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

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

¥Note: This method is only available in the main process.

crashReporter.getUploadToServer()

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

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

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

¥Note: This method is only available in the main process.

crashReporter.setUploadToServer(uploadToServer)

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

  ¥uploadToServer boolean - Whether reports should be submitted to the server.

这通常由用户偏好控制。如果在调用 start 之前调用，这不会产生任何影响。

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

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

¥Note: This method is only available in the main process.

crashReporter.addExtraParameter(key, value)

• key 字符串 - 参数 key，不能超过 39 字节。

  ¥key string - Parameter key, must be no longer than 39 bytes.

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

  ¥value string - Parameter value, must be no longer than 127 bytes.

设置与崩溃报告一起发送的额外参数。当调用 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.

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

¥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.

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

¥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. 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 字符串 - 参数 key，不能超过 39 字节。

  ¥key string - Parameter key, must be no longer than 39 bytes.

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

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

crashReporter.getParameters()

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

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

在 Node 子进程中

¥In Node child processes

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

¥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 的版本。

  ¥ver string - The version of Electron.

• platform 字符串 - 例如 'win32'。

  ¥platform string - e.g. 'win32'.

• process_type 字符串 - 例如 'renderer'。

  ¥process_type string - e.g. 'renderer'.

• guid 字符串 - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72'。

  ¥guid string - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'.

• _version 字符串 - package.json 版本。

  ¥_version string - The version in package.json.

• _productName 字符串 - crashReporter options 对象中的产品名称。

  ¥_productName string - The product name in the crashReporter options object.

• prod 字符串 - 基础产品的名称。在本例中是 Electron。

  ¥prod string - Name of the underlying product. In this case Electron.

• _companyName 字符串 - crashReporter options 对象中的公司名称。

  ¥_companyName string - The company name in the crashReporter options object.

• upload_file_minidump 文件 - 崩溃报告的格式为 minidump。

  ¥upload_file_minidump File - The crash report in the format of minidump.

• crashReporter options 对象中 extra 对象的所有一级属性。

  ¥All level one properties of the extra object in the crashReporter options object.