Electron 集成指南 Electron integration guide

原文地址：Electron integration guide

原文作者：Bugsnag

译文出自：掘金翻译计划

将 Bugsnag 添加到你的 Electron（v10.1.4+）项目中，以在生成环境中自动捕获和报告错误。

Bugsnag Electron 当前只能捕获 JavaScript 错误。对原生应用的崩溃（minidumps）支持即将推出。如需抢先体验，请联系我们

安装 Installation

从 npm 或者 yarn 安装 Bugsnag：

npm install --save @bugsnag/electron
# or
yarn add @bugsnag/electron

基本配置 Basic configuration

要在应用程序中的任意点捕获错误：

在主进程应用程序入口文件的开头中初始化，通常是 main.js 或者 index.js。
在每个渲染进程第一个加载的 JavaScript 文件开头初始化。

Bugsnag 必须在主进程和渲染进程中都被初始化以捕获所有的错误。

主进程 Main process

const Bugsnag = require('@bugsnag/electron')

在你的应用程序入口，用你的 API key 和其他选项作为配置启动 Bugsnag：

Bugsnag.start({
  apiKey: 'YOUR_API_KEY',
  otherOptions: value,
})

你可以在_项目设置_中找到你的 API key。

大部分配置选项在从主进程调用 Bugsnag.start() 被提供，并且将会被全部渲染进程继承。

查看配置选项参考以获取可用的选项列表。

渲染进程 Renderer processes

// ES module-style 引入
import Bugsnag from '@bugsnag/electron'

// common-js/node-style 引入（当 nodeIntegration=true 时有用）
const Bugsnag = require('@bugsnag/electron')

当 webPreferences.nodeIntegration 是 false，需要使用 bundler（譬如 Webpack）来解析渲染进程代码中的依赖。当它为 true 时，require() 就像在 Node.js 中一样起作用。@bugsnag/electron 支持这两种情况。

需要的时候用渲染进程特定的配置来启动 Bugsnag：

Bugsnag.start({
  // renderer options
})

渲染进程从主进程中继承所有配置。仅有一些配置选项能在渲染进程中被设置。配置选项参考展示每个选项在那个进程中被支持。

TypeScript 支持 TypeScript support

类型定义是提供的，且当你引入任何顶级 @bugsnag/* 包时，类型定义将被 TypeScript 编译器自动化拾取，。

框架集成 Framework integration

Bugsnag 通过使用插件与渲染进程中 JavaScript UI 框架集成。

React

Bugsnag 的 React 插件提供一个 Error Boundary 组件，你可以使用这个组件捕获 React 组件中的带有元数据的渲染错误。

import BugsnagPluginReact from '@bugsnag/plugin-react'

Bugsnag.start({
  plugins: [new BugsnagPluginReact()]
})

更多信息请参阅 React 指南。

Vue

Bugsnag 的 Vue 插件挂钩到 Vue 的内置错误处理程序，以自动化从 Vue 组件中报告带有元数据的错误。

import BugsnagPluginVue from '@bugsnag/plugin-vue'

Bugsnag.start({
  plugins: [new BugsnagPluginVue()]
})

更多信息请参阅 Vue 指南。

Angular

Bugsnag 的 Angular 插件与 Angular 的内置错误处理程序集成，以自动化从 Angular 组件和服务中报告带有元数据的错误.

import { BugsnagErrorHandler } from '@bugsnag/plugin-angular'

export function errorHandlerFactory() {
  return new BugsnagErrorHandler()
}

@NgModule({
  /* Pass the BugsnagErrorHandler class along to the providers for your module */
  /* 传递 BugsnagErrorHandler 类给模块的 providers */
  providers: [ { provide: ErrorHandler, useFactory: errorHandlerFactory } ]
  /* other properties passed to the decorator omitted for brevity */
  /* 为了简洁，其他传递给 decorator 的属性被省略 */
})

更多信息请参阅 Angular 指南。

显示完整的堆栈路径 Showing full stacktraces

上传 source map 和 symbol 文件能够使你看见堆栈路径中原始的方法名、文件路径以及行号。

在你发布过程中，请参阅显示完整的堆栈路径以配置上传文件。

报告未处理的错误 Reporting unhandled errors

在完成安装和基本配置后，未处理的异常和未处理的 promise 拒绝将被报告，并自动出现在你的 Bugsnag 仪表板中。

报告已处理的错误 Reporting handled errors

有时候手动通知 Bugsnag 问题是有用的。为此，请调用 Bugsnag.notify()。譬如：

try {
  something.risky()
} catch (e) {
  Bugsnag.notify(e)
}

当报告已处理错误时，发送自定义的诊断数据或者调整特定错误的严重性经常是有帮助的。更多信息，请参阅报告已处理错误

发送诊断数据 Sending diagnostic data

Bugsnag 将为所有异常自动化捕捉以下数据：

完整的 堆栈路径
应用状态 包含运行时间以及前台时间
构建信息 包含应用名称、版本/构建、发布阶段
设备规格 包含操作系统版本、屏幕尺寸、总内存
系统状态 包含剩余内存、系统是否空闲、在线状态
脚本内容，如果错误源自内联 <script/> 标签
当前 URL，如果错误发生在调用 BrowserWindow.loadURL() 之后

附加自定义诊断 Attaching custom diagnostics

附加应用特定诊断数据到错误报告经常会很有帮助。这能通过设置一个回调来完成，这个回调将在任何报告发送给 Bugsnag 前被调用。

下面将数据 map 添加到 Bugsnag 仪表板上的 “company” 标签，以用于所有捕获的事件。

Bugsnag.start({
  onError: function (event) {
    event.addMetadata('company', {
      name: "Acme Co.",
      country: "uk"
    })
  }
})

更多信息请参阅自定义错误报告。

识别用户 Identifying users

为了将错误与顾客报告关联起来、或者查阅遇到每个错误的用户列表，在你的 Bugsnag 仪表板上捕获并展示用户信息会有帮助。

你可以通过 Bugsnag 启动时使用 user 配置属性或者通过使用 Bugsnag.setUser() 设置错误报告的用户信息。

Bugsnag.setUser('3', 'erina@example.com', 'Erina')

有关执行此操作的信息，请查阅添加用户数据。

记录 breadcrumbs Logging breadcrumbs

为了理解你的应用在每个崩溃前发生了什么，留下我们称之为 breadcrumbs 的简短日志语句会有帮助。每个错误报告都附加一个可配置数量的 breadcrumbs，以帮助诊断导致错误的事件。

默认情况下，Bugsnag 捕获下面的事件作为 breadcrumbs：

应用生命周期事件
点击
控制台日志、警告和错误
Display 添加、移除和调整大小事件
Error 错误
HTTP 请求
电源状态变化，像切换到电池电源
窗口可见性变化

有关更多信息或者禁用特定类别的自动 breadcrumb 生成，请查阅配置选项。

你可以使用 leaveBreadcrumb 方法以记录你自己应用程序中潜在有用的事件：

Bugsnag.leaveBreadcrumb('Button clicked')

Bugsnag 将跟踪 breadcrumbs 的时间和顺序，并展示到你的仪表板中。通过提供可选的 metadata 参数，其他数据也能被附加到 breadcrumbs。

有关如何集成自定义 breadcrumbs 的更多信息和示例，请查阅自定义 breadcrumbs

会话跟踪 Session tracking

Bugsnag 跟踪你应用中发生的”会话“数量。这允许你比较发布版本间的稳定性分数，并且帮助你理解你的发布版本的质量。

会话在默认情况下被捕获和报告。可使用 autoTrackSessions 配置选项禁用这一行为。

Bugsnag 将在每次应用启动或者在后台运行至少60秒后进入前台时自动报告会话。

有关会话跟踪或者自定义会话跟踪，请查阅捕获会话。

识别启动时崩溃 Identifying crashes at launch

默认情况下 Bugsnag 将识别你的应用正在启动时发生的奔溃，让你能优先修复影响面较大的启动崩溃。

按照识别启动时崩溃指南来配置这一功能。