跳到主要內容

crashReporter

將當機報告提交至遠端伺服器。

程序：主要、渲染

以下是如何設定 Electron 自動將當機報告提交至遠端伺服器的範例

const { crashReporter } = require('electron')

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

關於設定伺服器以接收和處理當機報告，您可以使用以下專案

注意： Electron 使用 Crashpad 而非 Breakpad 來收集和上傳當機報告，但目前 上傳協定是相同的。

或者使用第三方託管解決方案

當機報告在上傳前會暫時儲存在應用程式使用者資料目錄下的 'Crashpad' 目錄中。您可以在啟動當機報告器之前呼叫 app.setPath('crashDumps', '/path/to/crashes') 來覆寫此目錄。

Electron 使用 crashpad 來監控和報告當機。

方法​

crashReporter 模組有以下方法

crashReporter.start(options)​

  • options 物件
    • submitURL 字串 (選用) - 當機報告將以 POST 形式傳送到的 URL。除非 uploadToServer 為 false，否則為必填。
    • productName 字串 (選用) - 預設為 app.name。
    • companyName 字串 (選用) 已棄用 - 已棄用的 { globalExtra: { _companyName: ... } } 別名。
    • uploadToServer 布林值 (選用) - 是否應將當機報告傳送到伺服器。如果為 false，則會收集當機報告並儲存在 crashes 目錄中，但不會上傳。預設值為 true。
    • ignoreSystemCrashHandler 布林值 (選用) - 如果為 true，則主要程序中產生的當機將不會轉發至系統當機處理程式。預設值為 false。
    • rateLimit 布林值 (選用) macOS Windows - 如果為 true，則限制每小時上傳的當機次數為 1 次。預設值為 false。
    • compress 布林值 (選用) - 如果為 true，則會壓縮當機報告並使用 Content-Encoding: gzip 上傳。預設值為 true。
    • extra Record<string, string> (選用) - 將與在主要程序中產生的當機報告一起傳送的額外字串鍵/值註釋。僅支援字串值。在子程序中產生的當機報告將不包含這些額外參數，若要將這些參數加入至子程序產生的當機報告中，請從子程序呼叫 addExtraParameter。
    • globalExtra Record<string, string> (選用) - 將與在任何程序中產生的任何當機報告一起傳送的額外字串鍵/值註釋。一旦啟動當機報告器，就無法變更這些註釋。如果鍵同時存在於全域額外參數和程序特定的額外參數中，則全域額外參數將優先。根據預設，會包含 productName 和應用程式版本，以及 Electron 版本。

此方法必須在使用任何其他 crashReporter API 之前呼叫。一旦以此方式初始化，crashpad 處理程式會從所有後續建立的程序中收集當機報告。一旦啟動，當機報告器就無法停用。

此方法應盡可能在應用程式啟動時盡早呼叫，最好在 app.on('ready') 之前呼叫。如果建立渲染程序時未初始化當機報告器，則該渲染程序將不受當機報告器監控。

注意： 您可以使用 process.crash() 產生當機來測試當機報告器。

注意： 如果您需要在第一次呼叫 start 後傳送其他/更新的 extra 參數，您可以呼叫 addExtraParameter。

注意： 在 extra、globalExtra 中傳遞或使用 addExtraParameter 設定的參數對鍵和值的長度有限制。鍵名稱的長度最多只能為 39 個位元組，而值的長度不得超過 127 個位元組。超過最大長度的鍵名稱將會被靜默忽略。超過最大長度的鍵值將會被截斷。

注意： 此方法僅在主要程序中可用。

crashReporter.getLastCrashReport()​

返回 CrashReport | null - 上次當機報告的日期和 ID。只會傳回已上傳的當機報告；即使磁碟上存在當機報告，也只有在上傳後才會傳回。如果沒有上傳的報告，則會傳回 null。

注意： 此方法僅在主要程序中可用。

crashReporter.getUploadedReports()​

返回 CrashReport[]

傳回所有已上傳的當機報告。每個報告都包含日期和已上傳的 ID。

注意： 此方法僅在主要程序中可用。

crashReporter.getUploadToServer()​

返回 boolean - 是否應將報告提交至伺服器。透過 start 方法或 setUploadToServer 設定。

注意： 此方法僅在主要程序中可用。

crashReporter.setUploadToServer(uploadToServer)​

  • uploadToServer 布林值 - 是否應將報告提交至伺服器。

這通常由使用者偏好設定控制。如果在呼叫 start 之前呼叫，則不會產生任何作用。

注意： 此方法僅在主要程序中可用。

crashReporter.addExtraParameter(key, value)​

  • key 字串 - 參數鍵，長度不得超過 39 個位元組。
  • value 字串 - 參數值，長度不得超過 127 個位元組。

設定要與當機報告一起傳送的額外參數。此處指定的值將會與呼叫 start 時透過 extra 選項設定的任何值一起傳送。

以這種方式新增的參數（或透過 crashReporter.start 的 extra 參數新增的參數）特定於呼叫的程序。在主要程序中新增額外參數不會導致這些參數與來自渲染器或其他子程序的當機一起傳送。同樣地，在渲染程序中新增額外參數也不會導致這些參數與在其他渲染程序或主要程序中發生的當機一起傳送。

注意： 參數對鍵和值的長度有限制。鍵名稱的長度不得超過 39 個位元組，而值的長度不得超過 20320 個位元組。超過最大長度的鍵名稱將會被靜默忽略。超過最大長度的鍵值將會被截斷。

crashReporter.removeExtraParameter(key)​

  • key 字串 - 參數鍵，長度不得超過 39 個位元組。

從目前的參數集中移除額外參數。未來的當機將不會包含此參數。

crashReporter.getParameters()​

返回 Record<string, string> - 當機報告器目前的「額外」參數。

在 Node 子程序中​

由於 require('electron') 在 Node 子程序中不可用，因此以下 API 在 Node 子程序中的 process 物件上可用。

process.crashReporter.start(options)​

請參閱 crashReporter.start()。

請注意，如果在主進程中啟動了崩潰報告器，它會自動監控子進程，因此不應在子進程中啟動。只有在主進程未初始化崩潰報告器時才應使用此方法。

process.crashReporter.getParameters()​

請參閱 crashReporter.getParameters()。

process.crashReporter.addExtraParameter(key, value)​

請參閱 crashReporter.addExtraParameter(key, value)。

process.crashReporter.removeExtraParameter(key)​

請參閱 crashReporter.removeExtraParameter(key)。

崩潰報告有效負載​

崩潰報告器將以 multipart/form-data POST 的形式，將以下數據發送到 submitURL

  • 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 物件的所有第一層屬性。