Electron 错误还原

Electron 应用包含 JavaScript 错误和原生崩溃，两者使用不同的还原方式：

错误类型	原始调用栈	需要上传
主进程和渲染进程 JavaScript 错误	压缩后的文件名和行列号	构建生成的 sourcemap
Electron 或原生模块崩溃	模块名和内存地址	Breakpad `.sym` 文件

还原 JavaScript 错误

SDK 默认将应用目录中的栈帧转换为稳定的 app:///<相对路径>。无论用户把应用安装到哪里，同一份构建都会得到相同的路径。例如：

Error: something went wrong
  at handleClick @ app:///dist/renderer/index.js:97:15

上传时只使用 URL 的 path 部分。上例对应的目录前缀是 /dist/renderer。

1. 统一 service 和 version

Flashduty 使用以下信息匹配 sourcemap：

事件中的 service
事件中的 version
栈帧中的压缩文件路径

建议让主进程和渲染进程使用相同的版本变量：

main.ts

await init({
  // 其余配置
  service: 'my-electron-app',
  version: '1.4.2',
});

renderer.ts

flashcatRum.init({
  // 其余配置
  service: 'my-electron-app',
  version: '1.4.2',
});

主进程的 version 不会自动写入渲染进程事件，因此两侧都需要配置。

2. 生成 sourcemap

为主进程和渲染进程构建开启 sourcemap：

export default defineConfig({
  build: { sourcemap: true },
});

module.exports = {
  mode: 'production',
  devtool: 'source-map',
};

await esbuild.build({
  sourcemap: true,
});

3. 上传主进程和渲染进程产物

安装 Flashduty CLI，然后分别上传两个进程的 sourcemap：

npm install --global @flashcatcloud/flashcat-cli

# 主进程栈：app:///dist/main/index.js
flashcat-cli sourcemaps upload ./out/main \
  --service my-electron-app \
  --release-version 1.4.2 \
  --minified-path-prefix /dist/main \
  --api-key <YOUR_API_KEY>

# 渲染进程栈：app:///dist/renderer/index.js
flashcat-cli sourcemaps upload ./out/renderer \
  --service my-electron-app \
  --release-version 1.4.2 \
  --minified-path-prefix /dist/renderer \
  --api-key <YOUR_API_KEY>

--minified-path-prefix 应与错误详情中栈帧的目录一致。不要在前缀中包含 app:///。

不要将 .map 文件打入最终分发的应用包。完成上传后，请在生成安装包前从分发产物中排除它们。

自定义路径映射

大多数项目可以直接使用默认的 app:/// 路径。只有构建目录无法按应用根目录表达时，才配置 normalizeStackPath：

main.ts

await init({
  // 其余配置
  normalizeStackPath: (absolutePath) => {
    const normalized = absolutePath.replace(/\\/g, '/');
    const match = /\/public(\/dist\/.+)$/.exec(normalized);
    return match ? match[1] : undefined;
  },
});

该回调同时应用于主进程和通过桥接上报的渲染进程栈。返回 undefined 时，SDK 会继续使用默认规则。

还原原生崩溃

原生崩溃来自 Electron crashReporter 生成的 minidump。未上传符号时，调用栈会显示模块和地址：

0  Electron Framework  0x000000010ab12345
1  libsystem_kernel    0x00007ff81a2b3c4d

上传匹配的 Breakpad 符号后，Flashduty 可以还原函数名、文件名和行号。

1. 准备符号文件

从 Electron releases 下载与你实际发布的 Electron 版本、操作系统和 CPU 架构完全一致的符号包：

electron-v<version>-<platform>-<arch>-symbols.zip

真实崩溃中的大多数栈帧通常位于 Electron 自带模块中，因此建议优先上传官方符号包。如果应用包含自己的原生模块或 .node 插件，请使用 dump_syms 为这些模块生成 .sym 文件。

2. 上传符号

将 .sym 文件放在同一个目录中，然后执行：

flashcat-cli electron-symbols upload ./breakpad_symbols \
  --service my-electron-app \
  --release-version 1.4.2

使用 --dry-run 可以先查看将要上传的文件。单个 Breakpad .sym 文件的大小上限为 2 GB，超过限制的上传会被拒绝（HTTP 413）。原生符号按模块 ID 匹配。命令中的 service 和 release-version 用于标记上传批次，方便查询，不参与符号匹配。这一点与 JavaScript sourcemap 不同。

3. 随版本发布符号

每次升级 Electron 或重新构建原生模块后，模块 ID 都可能变化。请为实际发布的每个操作系统和 CPU 架构上传对应符号。未上传符号不会阻止崩溃事件上报。你可以先收到地址形式的崩溃栈，再补传符号；历史崩溃会在查看时重新还原。

在控制台上传 Electron 符号

除了命令行，你也可以在控制台完成原生符号的上传。进入 应用管理 → 源码管理 → Electron，该页签列出已上传的 Electron 符号：每个原生模块一行，展示模块、Debug ID、架构、服务、版本、大小和上传时间。列表支持按 Debug ID 自由搜索（该值即崩溃事件 binary_images 携带的模块 Debug ID），并可添加服务、版本和 build_id 筛选条件。点击 上传 Electron 符号 打开上传面板，填写以下参数后，面板会生成对应的上传命令：

字段	对应命令	说明
API Key	`FLASHCAT_API_KEY`	用于认证上传请求
符号文件目录	位置参数	存放 `.sym` 文件的目录，会递归查找并逐个上传，例如 `./breakpad_symbols`
服务名	`--service`	仅用于本页归类查找，建议与 SDK 初始化时的 `service` 一致
发布版本	`--release-version`	仅用于本页归类查找，建议与 SDK 初始化时的 `version` 一致
自定义上传 Endpoint	`FLASHCAT_SOURCEMAP_INTAKE_URL`	仅私有化部署显示。自动填入部署下发的上报地址，可手动覆盖（协议 + 域名，不带路径）；留空则默认上传到 Flashcat SaaS

FLASHCAT_API_KEY=<YOUR_API_KEY> flashcat-cli electron-symbols upload ./breakpad_symbols \
  --service my-electron-app \
  --release-version 1.4.2

面板还提供官方符号下载助手：输入 Electron 版本（默认 41.1.0）并选择 平台 / 架构（darwin-arm64、darwin-x64、win32-x64、win32-arm64、linux-x64、linux-arm64），即可生成对应版本的官方符号包下载地址，以及一条「下载 → 解压 → 上传」的一行命令：

curl -fsSL "https://github.com/electron/electron/releases/download/v41.1.0/electron-v41.1.0-darwin-arm64-symbols.zip" -o electron-v41.1.0-symbols.zip && \
unzip -o electron-v41.1.0-symbols.zip -d ./breakpad_symbols && \
FLASHCAT_API_KEY=<YOUR_API_KEY> flashcat-cli electron-symbols upload ./breakpad_symbols --service my-electron-app --release-version 1.4.2

每次升级 Electron 都要重新上传对应版本的官方符号：不同 Electron 版本的二进制 Debug ID 不同，旧符号不会被匹配到。如果应用包含自己的原生模块或 .node 插件，展开 为自己的原生模块生成符号（可选），使用 dump_syms 生成 .sym 文件放入同一目录，例如：

dump_syms ./MyApp.app/Contents/MacOS/MyApp > ./breakpad_symbols/MyApp.sym

面板说明中提供「去 Web 页签上传 sourcemap」入口，用于还原 JavaScript 堆栈。面板还提供「复制给 AI 助手」入口（折叠区和底部按钮）：复制一段面向 coding agent 的英文提示词，指导它按步骤完成符号上传——从项目 package.json 读取 Electron 版本，下载对应平台和架构的官方符号包并解压，如有自定义原生模块或 .node 插件则用 dump_syms 生成 .sym，最后通过 flashcat-cli electron-symbols upload 上传。提示词会附带本页文档链接，并提醒通过环境变量注入 API Key、不要将密钥提交到仓库。

验证错误还原

JavaScript 错误

在测试版本中触发一个包含稳定调用栈的错误
在错误详情中确认事件的 service 和 version
检查栈帧路径与 --minified-path-prefix 是否对应
确认详情页显示原始文件名、函数名和源码位置

原生崩溃

使用与发布版本相同的 Electron 构建触发测试崩溃
重新启动应用，让 SDK 上报 minidump
在崩溃详情中确认 Electron 模块帧已显示函数名和行号

如果上传成功但调用栈仍未还原，请参阅 Electron SDK 问题排查。

高级配置

配置版本、路径映射和其他进阶选项。

数据收集

了解 JavaScript 错误与原生崩溃的采集方式。

快速开始

分析看板

SDK 接入

性能监控

异常追踪

查看器

会话重放

最佳实践

其他

还原 JavaScript 错误

1. 统一 service 和 version

2. 生成 sourcemap

3. 上传主进程和渲染进程产物

自定义路径映射

还原原生崩溃

1. 准备符号文件

2. 上传符号

3. 随版本发布符号

在控制台上传 Electron 符号

验证错误还原

JavaScript 错误

原生崩溃

相关页面

高级配置

数据收集

​还原 JavaScript 错误

​1. 统一 service 和 version

​2. 生成 sourcemap

​3. 上传主进程和渲染进程产物

​自定义路径映射

​还原原生崩溃

​1. 准备符号文件

​2. 上传符号

​3. 随版本发布符号

​在控制台上传 Electron 符号

​验证错误还原

​JavaScript 错误

​原生崩溃

​相关页面

高级配置

数据收集

还原 JavaScript 错误

1. 统一 service 和 version

2. 生成 sourcemap

3. 上传主进程和渲染进程产物

自定义路径映射

还原原生崩溃

1. 准备符号文件

2. 上传符号

3. 随版本发布符号

在控制台上传 Electron 符号

验证错误还原

JavaScript 错误

原生崩溃

相关页面