人人都会AI编程

21.2 崩溃捕获：crashReporter、崩溃日志收集与分析

更新时间：2026-07-11

桌面应用与 Web 应用有一个关键区别：Web 页面的崩溃通常只影响一个标签页，而桌面应用任何进程的异常退出都可能丢失用户数据，严重时甚至导致整个程序不可用。因此，有效的崩溃监控和日志收集对于 Electron 应用的稳定性至关重要。Electron 提供了一套内置的崩溃报告机制 —— crashReporter，可以自动捕获主进程和渲染进程的崩溃，生成 minidump 文件并上传到指定的服务器，帮助你快速定位问题。

21.2.1 crashReporter 的工作原理

crashReporter 模块利用了 Chromium 和 Node.js 各自的崩溃报告基础设施：

  • 渲染进程崩溃：由 Chromium 内置的 Breakpad 或 Crashpad 客户端处理。当某个渲染进程意外终止时，会生成一份进程的 minidump（.dmp 文件），包含崩溃时的调用栈、寄存器状态、加载的模块等信息。
  • 主进程崩溃：主进程运行在 Node.js 环境下，崩溃时也会生成 minidump。需要注意的是，默认情况下 Node.js 自身的异常（如未捕获的 JavaScript 错误）并不会触发底层崩溃，只有类似 C++ 层的严重错误（段错误、断言失败）才会被捕获。因此你还需结合 process.on('uncaughtException') 来捕获 JS 层的崩溃，这部分已在 21.1 节讨论。

一旦 crashReporter 启动，每一次子进程（渲染进程、GPU 进程等）的崩溃都会被记录，并自动将 minidump 文件上传到你配置的服务器端点。上传是异步进行的，不会阻塞应用的正常运行。

21.2.2 基本配置

在应用启动时，应该尽早调用 crashReporter.start()，最好放在主进程 app.whenReady() 之前，以确保所有崩溃都能被捕获。一个典型的配置如下：

const { crashReporter } = require('electron');

crashReporter.start({
  // 必填：公司名称，用于在不同平台生成崩溃报告的路径
  companyName: 'MyCompany',
  // 必填：上传崩溃报告的服务器 URL，支持 http 和 https
  submitURL: 'https://crash.mycompany.com/submit',
  // 可选：是否自动上传，默认为 true，设为 false 则需要手动调用 crashReporter.uploadCrashes()
  uploadToServer: true,
  // 可选：额外的键值对，会附加到每次崩溃报告中，方便标记版本、环境等
  extra: {
    appVersion: app.getVersion(),
    platform: process.platform,
    electronVersion: process.versions.electron,
  },
  // 可选：是否忽略系统崩溃处理程序，默认 false
  ignoreSystemCrashHandler: false,
  // 可选：是否以异步模式运行 (Crashpad 支持)，Windows 上有效
  rateLimit: true,
  // 在 macOS 上，若希望调试时也能生成报告，可设置
  globalExtra: { _version: app.getVersion() }
});

21.2.3 手动控制上传和生成额外上下文

对于包含敏感信息的应用，你可能希望先对崩溃报告进行过滤或增加用户导出的功能。此时可以将 uploadToServer 设为 false，再在合适时机调用 crashReporter.uploadCrashes() 批量上传。

你还可以利用 crashReporter.addExtraParameter(key, value) 和 crashReporter.removeExtraParameter(key) 在运行时动态添加额外参数。例如，在用户登录后附加用户 ID，这样当崩溃发生时就能精确追踪到受影响的用户：

crashReporter.addExtraParameter('userId', activeUser.id);

当用户登出或切换到访客模式时，应该及时移除该参数，防止隐私泄漏。

21.2.4 崩溃日志的收集与分析

收集端

Electron 官方并未限定后端实现，任何能接收 multipart/form-data POST 请求的 HTTP 服务均可。一个最简单的 Node.js + Express 接收端示例：

const express = require('express');
const multer = require('multer');
const upload = multer({ dest: 'dumps/' });
const app = express();

app.post('/submit', upload.single('upload_file_minidump'), (req, res) => {
  // req.file 包含 minidump 文件
  // req.body 包含 extra 参数、prod（产品名，默认 Electron）、ver 等
  console.log('Crash report received:', req.body);
  res.sendStatus(200);
});

app.listen(3000);

推荐使用 Sentry 等成熟的崩溃监控服务，它们对 Electron 有原生支持，并提供符号化、聚合、告警等功能。如果自行搭建，建议将 minidump 文件存储在对象存储中，并在数据库中记录元数据（版本、平台、上传时间、用户 ID 等），便于检索。

符号化

minidump 文件本质上是二进制快照，包含的内存地址需要与程序的调试符号（.pdb / .dSYM）匹配才能还原成可读的函数名和行号。因此，在构建 Electron 应用时务必保留符号文件，并在你的崩溃分析服务中集成符号化步骤。

对于 Electron 主进程和自带模块，可以从 Electron 官方符号服务器（https://electron-symbols.githubapp.com）获取对应的符号。对于你自己的原生 Node 模块，需要自行保存编译生成的 .pdb 或 .dSYM 文件。

常用的本地分析工具包括 Google 的 minidump_stackwalk 或 breakpad_tools，它们可以将 minidump 转换为可读的栈追踪信息。例如，使用 minidump_stackwalk 分析一个 dump 文件：

minidump_stackwalk crash.dump symbols/ > crash_report.txt

在自动化流水线中，你可以使用 electron-minidump 或 sentry-cli 进行自动符号化和上传。

21.2.5 渲染进程崩溃的特殊处理

虽然 crashReporter 可以自动记录渲染进程崩溃，但用户体验上，窗口突然消失会让用户不知所措。你可以监听主进程的 webContents 上的 'crashed' 事件，在窗口崩溃时向用户展示友好提示或尝试重新加载：

win.webContents.on('crashed', (event, killed) => {
  console.log('Renderer process crashed, killed:', killed);
  // 显示自定义崩溃页面
  win.loadFile('crash.html');
  // 或者重新创建窗口
});

注意，'crashed' 事件在渲染进程被系统强制终止（如 OOM 杀掉）时也可能触发，此时 killed 参数为 true。

21.2.6 最佳实践

  1. 尽早启动：在 app 的 ready 事件前调用 crashReporter.start()，覆盖主进程初始化阶段的崩溃。
  2. 保护隐私：不要将明文密码、完整文件路径等敏感信息放入 extra。在发布前审核附带的参数。
  3. 结合 JavaScript 异常监控：crashReporter 只处理二进制层崩溃，应配合 uncaughtException 和 unhandledRejection 监控 JS 错误，保持全面的崩溃覆盖。
  4. 保留符号文件：每次发版时，将本次构建的符号文件打包存档，对应版本的崩溃报告才能被完全符号化。
  5. 定期清理本地崩溃缓存：Electron 默认将未上传的崩溃报告存储在临时目录，长时间运行可能堆积。可通过 crashReporter.getCrashesDirectory() 获取路径，结合应用启动时清理过旧的 dump 文件。
  6. 测试上传链路：使用 crashReporter.generateCrashReport() 或 process.crash()（主进程）可以强制生成测试崩溃，验证端到端流程是否正常。

21.2.7 实例：集成 Sentry

Sentry 的 @sentry/electron 包封装了 crashReporter 配置，同时接管了 JS 异常和 native 崩溃。一个最小化集成如下：

const Sentry = require('@sentry/electron');

Sentry.init({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
  // 可选：采样率、环境、版本等
  tracesSampleRate: 1.0,
});

Sentry 会自动启动 crashReporter，将崩溃报告与已经捕获的 JS 错误统一展示，极大地简化了崩溃分析流程。对于不想自建收集服务的团队，这是性价比最高的方案。

21.2.8 小结

crashReporter 是 Electron 应用稳定性监控的基石，它让原本难以捉摸的原生崩溃变得可观测、可追溯。关键要点是正确配置上传参数，搭配符号化服务将地址翻译成有意义的堆栈，并结合用户感知层（如崩溃提示窗口）提供更友好的体验。无论你选择自建收集管道还是使用第三方服务，持续关注并解决上报的崩溃，是向用户交付高品质桌面软件的必经之路。