crashReporter

将崩溃日志提交给远程服务器

ProcessMainRenderer

[!IMPORTANT] If you want to call this API from a renderer process with context isolation enabled, place the API call in your preload script and expose it using the contextBridge API.

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

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

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.

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.

On Windows, some crashes never reach an in-process crash handler, most notably __fastfail terminations (STATUS_STACK_BUFFER_OVERRUN, raised by security-check failures, Control Flow Guard violations and the C runtime's abort()). To capture these, Electron ships electron_wer.dll, a Windows Error Reporting (WER) runtime exception helper that Windows (10 20H1 and later) loads out-of-process after such a crash and that asks the crashpad handler to write a minidump. When crashReporter.start() is called, Electron lists the DLL under HKEY_CURRENT_USER\Software\Microsoft\Windows\Windows Error Reporting\RuntimeExceptionHelperModules, which Windows requires before it will load a helper, and registers it for every Electron process. The helper is looked up as <executable name>_wer.dll next to the executable, so if you rename electron.exe to myapp.exe when packaging, rename electron_wer.dll to myapp_wer.dll as well. Installers that write to HKEY_LOCAL_MACHINE may list it there instead. To opt out, do not ship the DLL.

方法

crashReporter 模块具有以下方法:

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.

• 选项 对象
  • submitURL string (可选) - 崩溃报告将以POST的方式发送给这个URL。必填 除非uploadToServer是false
  • productName string (可选) - 默认为 app.name.
  • companyName string (可选) 已废弃 - 已废弃别名为{ globalExtra: { _companyName: ... } }。
  • uploadToServer boolean (可选) - 是否将崩溃报告发送给服务器。如果为 false，崩溃报告将被收集并存储在崩溃目录中，但不会上传。默认值为 true。
  • ignoreSystemCrashHandler boolean (optional) macOS Linux - If true, crashes generated in the main process will not be forwarded to the system crash handler. This option has no effect on Windows. 默认值为 false.
  • rateLimit boolean (optional) - If true, limit the number of crashes uploaded to 1/hour. Crash reports over the limit are not uploaded, but are still stored on disk. 默认值为 false.
  • compress boolean (可选) - 如果为true，崩溃报告将压缩并上传，使用带有 Content-Encoding: gzip 的头部。 Setting this to false while uploadToServer is true is deprecated and logs a deprecation warning. 默认值为 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. 只支持string值。 Crashes generated in child processes will not include these extra parameters. To add extra parameters to crash reports generated from child processes, call addExtraParameter from the child process.
  • globalExtra Record<string, string> (optional) - Extra string key/value annotations that will be sent along with any crash reports generated in any process. 一旦崩溃报告器启动，这些注解就无法更改。如果一个键在global extra参数和进程特定的额外参数中出现，那么全局的那个将优先使用。默认情况下，会包括 productName 和应用程序版本，也就是Electron版本。 Global extra parameters are not returned by getParameters().

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

该方法应尽早地在app启动后调用，最好在 app.on('ready') 之前。如果崩溃报告器没有在渲染器进程创建前初始化，那么渲染器进程将不会被崩溃报告器监视。

[!NOTE] You can test out the crash reporter by generating a crash using process.crash().

[!NOTE] If you need to send additional/updated extra parameters after your first call start you can call addExtraParameter.

[!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 20320 bytes. Keys with names longer than the maximum are ignored, and a warning is emitted. Values longer than the maximum length are truncated.

[!NOTE] This method is only available in the main process.

crashReporter.getLastCrashReport()

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

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.

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

crashReporter.getUploadedReports()

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

Returns CrashReport[]:

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.

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

crashReporter.getUploadToServer()

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

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

[!NOTE] This method is only available in the main process.

crashReporter.setUploadToServer(uploadToServer)

History

Version(s)	Changes
None	Deprecated calling this method in the renderer process.

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

通常由用户首选项控制。如果在 start 被调用前调用，该方法将不起作用。

[!NOTE] This method is only available in the main process.

crashReporter.addExtraParameter(key, value)

• key string - 参数键，长度必须小于39个字节。
• value string - 参数值，长度必须小于20320个字节。

设置一个在发送崩溃报告时将额外包含的参数。当调用 start 时, 在这里指定的值会和所有通过 extra 选项设置的值一起发送。 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.

以这种方式添加的参数 (或通过 extra 参数到crashReporter.start)是特定于调用进程的。在主进程中添加extra参数，这些参数将不会与渲染器或其它子进程的崩溃报告一起发送。同样，在渲染器进程中添加的extra参数不会与其它渲染器进程或主进程中发生的崩溃一起发送。 Processes created with utilityProcess have no API for setting extra parameters, so only globalExtra values are sent with their crashes.

[!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 are ignored, and a warning is emitted. Values longer than the maximum length are truncated.

crashReporter.removeExtraParameter(key)

• key string - 参数键，长度必须小于39个字节。

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

crashReporter.getParameters()

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 子进程中

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.

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()

See crashReporter.getParameters().

process.crashReporter.addExtraParameter(key, value)

See crashReporter.addExtraParameter(key, value).

process.crashReporter.removeExtraParameter(key)

See crashReporter.removeExtraParameter(key).

崩溃报告内容

崩溃报告将发送下面 multipart/form-data POST 型的数据给 submitURL. 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 - e.g. 'renderer', or 'browser' for the main process.
• guid string - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72'.
• _version string - package.json 里的版本号.
• _productName string - crashReporter options 对象中的产品名字
• prod string - 基础产品的名称。在这种情况下是Electron。
• _companyName string - crashReporter options 对象中的公司名称 Only sent if the deprecated companyName option is set.
• upload_file_minidump File - minidump 格式的崩溃报告
• All level one properties of the globalExtra object in the crashReporter options object.
• All extra parameters of the process that crashed, set with the extra option (main process only) or addExtraParameter.

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.

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