> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Electron SDK 兼容性

> 查看 Electron RUM SDK 支持的版本、操作系统、打包工具和当前限制

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

## 支持范围

| 项目        | 支持情况                                          |
| --------- | --------------------------------------------- |
| Electron  | 30 或更高版本                                      |
| 操作系统      | 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 30–34：应用若自行调用 `session.setPreloads()`，会顶掉桥接 | 这个版本区间没有 `registerPreloadScript`，桥接改由 `setPreloads` 注册，而它是整体替换而非追加。按窗口用 `webPreferences.preload` 设置预加载不受影响 |
| Electron 30–36：Electron 自带的 `net` 模块不被追踪             | 该版本区间内，用 `net.request` / `net.fetch` 发出的请求不会产生 resource 事件；Node 的 `http`/`https` 和全局 `fetch` 不受影响，各版本都正常   |

详细排查方法见 [Electron SDK 问题排查](/zh/rum/sdk/electron/faq)。

## 相关页面

<CardGroup cols={2}>
  <Card title="SDK 接入指南" icon="plug" href="/zh/rum/sdk/electron/sdk-integration">
    完成主进程与渲染进程接入。
  </Card>

  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/electron/advanced-config">
    配置自定义上报地址与公开 API。
  </Card>

  <Card title="数据收集" icon="database" href="/zh/rum/sdk/electron/data-collection">
    了解每个进程采集的数据类型。
  </Card>

  <Card title="错误还原" icon="bug" href="/zh/rum/sdk/electron/error-symbolication">
    还原 JavaScript 和原生崩溃调用栈。
  </Card>
</CardGroup>