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 a guide to collecting, receiving and symbolicating crash reports, including how to run your own crash server or use a hosted service, see the Crash Reporting tutorial.

Electron 使用 Crashpad 来监控和报告崩溃。Crashpad 使用和 Breakpad 一样的 上传协议，所以接受 Breakpad minidump 的服务器也能接收 Electron 的崩溃报告。

🌐 Electron uses Crashpad to monitor and report crashes. Crashpad uses the same upload protocol as Breakpad, so servers that accept Breakpad minidumps can receive Electron's crash reports.

崩溃报告存储在 app.getPath('crashDumps') 返回的目录下。你可以在启动崩溃报告程序之前通过调用 app.setPath('crashDumps', '/path/to/crashes') 来重写它。这个目录中文件的布局是实现细节，可能会随 Electron 的版本变化而改变。

🌐 Crash reports are stored under the directory returned by app.getPath('crashDumps'). You can override it by calling app.setPath('crashDumps', '/path/to/crashes') before starting the crash reporter. The layout of files inside this directory is an implementation detail and may change between versions of Electron.

crashReporter 模块在 Mac 应用商店版本中被禁用。它的方法可以被调用，但不会有任何作用：不会收集或上传崩溃报告，getUploadedReports() 返回一个空数组，getUploadToServer() 返回 false。

🌐 The crashReporter module is disabled in Mac App Store builds. Its methods can be called, but they do nothing: no crash reports are collected or uploaded, getUploadedReports() returns an empty array and getUploadToServer() returns false.

方法​

🌐 Methods

crashReporter 模块具有以下方法：

🌐 The crashReporter module has the following methods:

crashReporter.start(options)​

History
Version(s)Changes
None

Added rateLimit and compress options.

None

Deprecated calling this method in the renderer process.

None

Default value of compress option changed from false to true.

None

The submitURL parameter is now optional when uploadToServer is false.

  • options 对象
    • submitURL string（optional）- 崩溃报告将作为 POST 发送到的 URL。除非 uploadToServer 为 false，否则为必填项。
    • productName string（optional）- 默认为 app.name。
    • companyName string (optional) Deprecated - 已弃用的 { globalExtra: { _companyName: ... } } 别名。
    • uploadToServer boolean（optional）- 是否应将崩溃报告发送到服务器。如果为 false，崩溃报告将被收集并存储在 crashes 目录中，但不会上传。默认值为 true。
    • ignoreSystemCrashHandler boolean (optional) macOS Linux - 如果为真，主进程中生成的崩溃将不会被转发到系统崩溃处理程序。这个选项在 Windows 上无效。默认值是 false。
    • rateLimit boolean（optional）- 如果为真，将上传的崩溃数量限制为每小时 1 次。超过限制的崩溃报告不会上传，但仍会存储在磁盘上。默认值是 false。
    • compress boolean（optional）- 如果为真，崩溃报告将会被压缩并通过 Content-Encoding: gzip 上传。在 uploadToServer 为 true 时将其设置为 false 已被弃用，并会记录一个弃用警告。默认值是 true。
    • extra Record<string, string>（optional）- 附加的字符串键/值注释，这些注释将随主进程生成的崩溃报告一起发送。仅支持字符串值。在子进程中生成的崩溃将不包含这些额外参数。要为子进程生成的崩溃报告添加额外参数，请在子进程中调用 addExtraParameter。
    • globalExtra Record<string, string>（optional）- 额外的字符串键/值注释，会随任何进程生成的崩溃报告一起发送。这些注释在崩溃报告器启动后无法更改。如果同一个键同时存在于全局额外参数和特定进程的额外参数中，全局的参数将优先使用。默认情况下，会包含 productName、应用版本以及 Electron 版本。全局额外参数不会被 getParameters() 返回。

在使用任何其他 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 字节，值最长不能超过 20320 字节。超过最大长度的键名会被忽略，并会发出警告。超过最大长度的值会被截断。

note

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

crashReporter.getLastCrashReport()​

History

返回 CrashReport | null - 从 getUploadedReports() 返回的列表中，上传时间最新的崩溃报告的日期和 ID。如果根本没有崩溃报告，则返回 null。

🌐 Returns CrashReport | null - The date and ID of the crash report with the most recent upload time, from the list returned by getUploadedReports(). If there are no crash reports at all, null is returned.

如果还没有上传报告，但有些报告存储在磁盘上，可能会返回尚未上传的报告。在将其视为已上传之前，先检查它的 id 是否为空。

🌐 If no report has been uploaded yet but some are stored on disk, a report that has not been uploaded may be returned. Check that its id is not empty before treating it as uploaded.

note

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

crashReporter.getUploadedReports()​

History

返回 CrashReport[]：

🌐 Returns CrashReport[]:

返回存储在磁盘上的崩溃报告。每个报告都包含上传日期和崩溃服务器返回的ID。

🌐 Returns the crash reports stored on disk. Each report contains the date it was uploaded and the ID that the crash server returned for it.

尽管方法的名称如此，但那些没有被上传的报告（例如因为 uploadToServer 是 false、上传失败，或者报告被限速）也会被包含在内。对于这些报告，id 是空字符串，date 没有实际意义。要只列出已上传的报告，可以过滤掉 id 为空的报告。

🌐 Despite the method's name, reports that have not been uploaded (for example because uploadToServer is false, the upload failed, or the report was rate limited) are included too. For those reports, id is an empty string and date is not meaningful. To list only uploaded reports, filter out reports with an empty id.

note

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

crashReporter.getUploadToServer()​

History

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

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

note

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

crashReporter.setUploadToServer(uploadToServer)​

History
  • uploadToServer boolean - 是否应将报告提交到服务器。

这通常由用户偏好控制。如果在调用 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 string - 参数键，长度不得超过39字节。
  • value string - 参数值，不能超过20320字节。

设置一个额外的参数随崩溃报告一起发送。这里指定的值会在调用 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. Calling this again with the same key replaces the value. The value is read when a crash happens, so you can update it as your app's state changes.

以这种方式添加的参数（或通过 crashReporter.start 的 extra 参数）是特定于调用进程的。在主进程中添加额外的参数不会导致这些参数随渲染器或其他子进程的崩溃一起发送。同样，在渲染器进程中添加额外参数，也不会导致这些参数随其他渲染器进程或主进程发生的崩溃发送。使用 utilityProcess 创建的进程没有设置额外参数的 API，所以它们崩溃时只会发送 globalExtra 的值。

🌐 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. Processes created with utilityProcess have no API for setting extra parameters, so only globalExtra values are sent with their crashes.

note

参数在键和值的长度上有一定限制。键名不能超过39字节，值不能超过20320字节。键名超过最大长度的会被忽略，并且会发出警告。值超过最大长度的会被截断。

crashReporter.removeExtraParameter(key)​

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

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

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

crashReporter.getParameters()​

返回 Record<string, string> - 调用进程中崩溃报告器的当前“额外”参数，这些参数是通过 extra 选项和 addExtraParameter 设置的。通过 globalExtra 选项设置的参数不包括在内。

🌐 Returns Record<string, string> - The current 'extra' parameters of the crash reporter in the calling process, as set with the extra option and addExtraParameter. Parameters set with the globalExtra option are not included.

在 Node 子进程中​

🌐 In Node child processes

由于 require('electron') 在 Node 子进程中不可用（以 ELECTRON_RUN_AS_NODE 运行的进程，例如使用 child_process.fork() 创建的进程），因此在 Node 子进程中可以通过 process 对象使用以下 API。

🌐 Since require('electron') is not available in Node child processes (processes run with ELECTRON_RUN_AS_NODE, such as those created with child_process.fork()), the following APIs are available on the process object in Node child processes.

如果在主进程中启动崩溃报告程序，Node 子进程会自动被监控。无法从 Node 子进程启动崩溃报告程序。

🌐 If the crash reporter is started in the main process, Node child processes are monitored automatically. There is no way to start the crash reporter from a Node child process.

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。除非 compress 是 false，否则请求体会进行 gzip 压缩并随 Content-Encoding: gzip 一起发送。

🌐 The crash reporter will send the following data to the submitURL as a multipart/form-data POST. Unless compress is false, the request body is gzip-compressed and sent with Content-Encoding: gzip.

  • ver string - Electron 的版本。
  • platform string - 例如 'win32'。
  • process_type string - 例如，主进程可以是“renderer”或“browser”。
  • guid string - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72'。
  • _version string - package.json 中的版本。
  • _productName string - crashReporter options 对象中的产品名称。
  • prod string - 基础产品的名称。在此情况下是 Electron。
  • _companyName string - crashReporter options 对象中的公司名称。仅在设置了已弃用的 companyName 选项时发送。
  • upload_file_minidump File - 以 minidump 格式的崩溃报告。
  • crashReporter options 对象中 globalExtra 对象的所有一级属性。
  • 所有导致进程崩溃的额外参数，都可以通过 extra 选项（仅主进程）或 addExtraParameter 设置。

Crashpad 和 Chromium 可能会在上传时添加其他字段。这些字段不是 Electron API 的一部分，可能随时更改，所以不要依赖它们。

🌐 Crashpad and Chromium may add other fields to the upload. These are not part of Electron's API and can change without notice, so don't rely on them.

服务器响应的内容被存储为崩溃报告的 ID，并通过 getUploadedReports() 返回在 id 字段中。

🌐 The body of the server's response is stored as the crash report's ID, and is returned in the id field by getUploadedReports().