Electron SDK 兼容性 - Flashduty Docs

接入前，请确认你的 Electron 版本和构建方式在支持范围内。

支持范围

项目	支持情况
Electron	39 或更高版本
操作系统	macOS、Windows、Linux
主进程 SDK	`@flashcatcloud/electron-sdk`
渲染进程 SDK	`@flashcatcloud/browser-rum` 0.0.7 或更高版本
模块格式	CommonJS、ESM
普通 RUM 上报	`POST https://<site>/api/v2/rum`，也可以配置自定义转发地址

打包工具

构建方式	支持情况	接入方式
主进程不打包	支持	在第一条 import 引入 `@flashcatcloud/electron-sdk/instrument`
Vite / electron-vite / Forge + Vite	支持	使用 `@flashcatcloud/electron-sdk/vite-plugin`
Webpack / Forge + Webpack	支持	使用 `@flashcatcloud/electron-sdk/webpack-plugin`
esbuild	支持	使用 `@flashcatcloud/electron-sdk/esbuild-plugin`
其他打包工具	需自行适配	保证 instrument 先于 Electron 加载，并将 `dd-trace` 和 Electron SDK 保留为运行时依赖

主进程打包时，请使用对应插件。插件会处理插桩的执行顺序、运行时依赖以及桥接 preload。

渲染进程页面加载方式

当前窗口加载的页面无需配置 host 白名单。

加载方式	支持情况	说明
`loadURL('http://localhost:<port>')`	支持	适用于本地开发服务
`loadURL('https://<host>')`	支持	当前页面自动允许使用桥接
自定义协议，例如 `app://`	支持	当前页面自动允许使用桥接
`loadFile()` / `file://`	支持	无需额外配置
`<webview>` / `BrowserView` 中的第三方页面	需配置	将第三方 host 添加到 `allowedWebViewHosts`

功能支持

能力	支持情况	说明
主进程会话与 view	支持	SDK 为主进程维护会话和固定 view
主进程 JavaScript 错误	支持	自动采集未捕获异常和未处理 Promise 拒绝
原生崩溃	支持	崩溃后生成 minidump，并在下次启动时上报
渲染进程终止	支持	采集 `render-process-gone` 和 `child-process-gone`
主进程网络请求	支持	采集 `http`、`https`、`fetch` 和 `net.fetch`
渲染进程页面体验	支持	与 Web SDK 一致，包含 view、action、resource、error 和 Web Vitals
会话回放	支持	需要渲染进程直传并允许相应 CSP
JavaScript sourcemap	支持	主进程和渲染进程均支持
原生崩溃符号还原	支持	需要上传匹配的 Breakpad 符号文件

当前限制

限制	影响
会话回放不经过主进程	回放需要在渲染进程配置 `sessionReplayDirectUpload`、CSP 和私有化转发地址
不提供完整 APM	当前只将主进程 HTTP span 转换为 RUM resource；IPC 和子进程 span 不会上报
不转发 Logs	渲染进程通过桥接发送的 log 事件不会作为 RUM 数据上报
主进程没有 Web Vitals	LCP、INP、CLS、long task 和用户操作来自渲染进程
主进程 RUM 事件不带 `env`	渲染进程事件仍保留 `flashcatRum.init()` 中的 `env`
预创建窗口指标校正仅覆盖 `BrowserWindow`	`WebContentsView` 和 `<webview>` 不会校正 FCP / LCP
原生崩溃需要符号文件	未上传符号时，崩溃事件仍会上报，但调用栈保持原始地址

详细排查方法见 Electron SDK 问题排查。

相关页面

SDK 接入指南

完成主进程与渲染进程接入。

高级配置

配置自定义上报地址与公开 API。

数据收集

了解每个进程采集的数据类型。

错误还原

还原 JavaScript 和原生崩溃调用栈。