跳到主要內容

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