> ## Documentation Index > Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt > Use this file to discover all available pages before exploring further. # Electron 错误还原 > 上传 Electron 应用的 JavaScript sourcemap 和原生崩溃符号，还原生产环境调用栈 Electron 应用包含 JavaScript 错误和原生崩溃，两者使用不同的还原方式： | 错误类型 | 原始调用栈 | 需要上传 | | ---------------------- | ----------- | ------------------ | | 主进程和渲染进程 JavaScript 错误 | 压缩后的文件名和行列号 | 构建生成的 sourcemap | | Electron 或原生模块崩溃 | 模块名和内存地址 | Breakpad `.sym` 文件 | ## 还原 JavaScript 错误 SDK 默认将应用目录中的栈帧转换为稳定的 `app:///<相对路径>`。无论用户把应用安装到哪里，同一份构建都会得到相同的路径。 例如： ```text theme={null} Error: something went wrong at handleClick @ app:///dist/renderer/index.js:97:15 ``` 上传时只使用 URL 的 path 部分。上例对应的目录前缀是 `/dist/renderer`。 ### 1. 统一 service 和 version Flashduty 使用以下信息匹配 sourcemap： * 事件中的 `service` * 事件中的 `version` * 栈帧中的压缩文件路径 建议让主进程和渲染进程使用相同的版本变量： ```ts main.ts theme={null} await init({ // 其余配置 service: 'my-electron-app', version: '1.4.2', }); ``` ```ts renderer.ts theme={null} flashcatRum.init({ // 其余配置 service: 'my-electron-app', version: '1.4.2', }); ``` 主进程的 `version` 不会自动写入渲染进程事件，因此两侧都需要配置。 ### 2. 生成 sourcemap 为主进程和渲染进程构建开启 sourcemap： ```ts Vite theme={null} export default defineConfig({ build: { sourcemap: true }, }); ``` ```js Webpack theme={null} module.exports = { mode: 'production', devtool: 'source-map', }; ``` ```ts esbuild theme={null} await esbuild.build({ sourcemap: true, }); ``` ### 3. 上传主进程和渲染进程产物 安装 [Flashduty CLI](https://github.com/flashcatcloud/flashcat-cli)，然后分别上传两个进程的 sourcemap： ```bash theme={null} npm install --global @flashcatcloud/flashcat-cli ``` ```bash theme={null} # 主进程栈：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 # 渲染进程栈：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 ``` `--minified-path-prefix` 应与错误详情中栈帧的目录一致。不要在前缀中包含 `app:///`。 不要将 `.map` 文件打入最终分发的应用包。完成上传后，请在生成安装包前从分发产物中排除它们。 ### 自定义路径映射 大多数项目可以直接使用默认的 `app:///` 路径。只有构建目录无法按应用根目录表达时，才配置 `normalizeStackPath`： ```ts main.ts theme={null} 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。未上传符号时，调用栈会显示模块和地址： ```text theme={null} 0 Electron Framework 0x000000010ab12345 1 libsystem_kernel 0x00007ff81a2b3c4d ``` 上传匹配的 Breakpad 符号后，Flashduty 可以还原函数名、文件名和行号。 ### 1. 准备符号文件 从 [Electron releases](https://github.com/electron/electron/releases) 下载与你实际发布的 Electron **版本、操作系统和 CPU 架构**完全一致的符号包： ```text theme={null} electron-v---symbols.zip ``` 真实崩溃中的大多数栈帧通常位于 Electron 自带模块中，因此建议优先上传官方符号包。 如果应用包含自己的原生模块或 `.node` 插件，请使用 [dump\_syms](https://github.com/mozilla/dump_syms) 为这些模块生成 `.sym` 文件。 ### 2. 上传符号 将 `.sym` 文件放在同一个目录中，然后执行： ```bash theme={null} 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 | ```bash theme={null} FLASHCAT_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`），即可生成对应版本的官方符号包下载地址，以及一条「下载 → 解压 → 上传」的一行命令： ```bash theme={null} 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= flashcat-cli electron-symbols upload ./breakpad_symbols --service my-electron-app --release-version 1.4.2 ``` 每次升级 Electron 都要重新上传对应版本的官方符号：不同 Electron 版本的二进制 Debug ID 不同，旧符号不会被匹配到。如果应用包含自己的原生模块或 `.node` 插件，展开 **为自己的原生模块生成符号（可选）**，使用 `dump_syms` 生成 `.sym` 文件放入同一目录，例如： ```bash theme={null} 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 错误 1. 在测试版本中触发一个包含稳定调用栈的错误 2. 在错误详情中确认事件的 `service` 和 `version` 3. 检查栈帧路径与 `--minified-path-prefix` 是否对应 4. 确认详情页显示原始文件名、函数名和源码位置 ### 原生崩溃 1. 使用与发布版本相同的 Electron 构建触发测试崩溃 2. 重新启动应用，让 SDK 上报 minidump 3. 在崩溃详情中确认 Electron 模块帧已显示函数名和行号 如果上传成功但调用栈仍未还原，请参阅 [Electron SDK 问题排查](/zh/rum/sdk/electron/faq#为什么-sourcemap-上传成功但错误栈没有还原)。 ## 相关页面 配置版本、路径映射和其他进阶选项。 了解 JavaScript 错误与原生崩溃的采集方式。