> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK 兼容性

> Web RUM SDK 支持的浏览器版本、框架和功能兼容性详细说明

<Info>
  本文档详细说明 Web RUM SDK 支持的浏览器、框架、打包工具以及相关限制，帮助您评估 SDK 在目标环境中的适用性。
</Info>

## 支持的浏览器

| 浏览器               | 桌面端 | 移动端 | 最低版本  | 备注             |
| ----------------- | --- | --- | ----- | -------------- |
| Chrome            | ✅   | ✅   | 63+   | 完整支持所有功能       |
| Firefox           | ✅   | -   | 67+   | 部分功能受限（见下方）    |
| Safari            | ✅   | ✅   | 12.1+ | 部分功能受限（见下方）    |
| Edge              | ✅   | -   | 79+   | 基于 Chromium 版本 |
| Opera             | ✅   | -   | 50+   | 完整支持所有功能       |
| Internet Explorer | ❌   | -   | -     | 不支持            |

<Warning>
  不支持 Internet Explorer 11 及更早版本。
</Warning>

## 浏览器功能兼容性

下表详细说明了各浏览器对 SDK 功能的支持情况：

| 功能           | Chrome | Firefox | Safari | Edge | Chrome Android | Safari iOS | Opera |
| ------------ | ------ | ------- | ------ | ---- | -------------- | ---------- | ----- |
| SDK 加载       | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| SDK 初始化      | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| RUM 数据上报     | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 页面隐藏时刷新      | ✅      | ✅       | ✅      | ✅    | ✅              | ❌          | ✅     |
| 控制台错误捕获      | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 运行时错误捕获      | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| CSP 违规检测     | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 浏览器干预检测      | ✅      | ❌       | ❌      | ✅    | ✅              | ❌          | ✅     |
| 自动操作追踪       | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 自定义操作追踪      | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 长任务检测        | ✅      | ❌       | ❌      | ✅    | ✅              | ❌          | ✅     |
| 分布式追踪        | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 路由变化追踪       | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 页面加载时间       | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| 资源性能监控       | ✅      | ✅       | ⚠️ (1) | ✅    | ✅              | ⚠️ (1)     | ✅     |
| 导航性能监控       | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |
| Web Vitals   | ✅      | ⚠️ (2)  | ⚠️ (2) | ✅    | ✅              | ⚠️ (2)     | ✅     |
| FCP (首次内容绘制) | ✅      | ✅       | ✅      | ✅    | ✅              | ✅          | ✅     |

**说明**：

1. 资源大小信息不可用
2. 仅支持 FID（首次输入延迟）指标

## 框架兼容性

### JavaScript 框架

<CardGroup cols={2}>
  <Card title="React" icon="react">
    支持 React 16.8+（Hooks），自动追踪 ✅
  </Card>

  <Card title="Vue.js" icon="vuejs">
    支持 Vue 2.x 和 Vue 3.x，自动追踪 ✅
  </Card>

  <Card title="Angular" icon="angular">
    支持 Angular 12+，自动追踪 ✅
  </Card>

  <Card title="Next.js" icon="code">
    支持 SSR 和客户端渲染，自动追踪 ✅
  </Card>

  <Card title="Nuxt.js" icon="code">
    支持 SSR 和客户端渲染，自动追踪 ✅
  </Card>

  <Card title="Svelte" icon="code">
    需要额外配置自动追踪 ⚠️
  </Card>
</CardGroup>

<Tip>
  原生 JavaScript（Vanilla JS）完全支持手动追踪功能。
</Tip>

### 打包工具

| 工具        | 支持状态 | 备注                 |
| --------- | ---- | ------------------ |
| Webpack   | ✅    | 支持所有主流版本（4.x, 5.x） |
| Vite      | ✅    | 推荐使用               |
| Rollup    | ✅    | 完整支持               |
| Parcel    | ✅    | 完整支持               |
| esbuild   | ✅    | 完整支持               |
| Turbopack | ✅    | 实验性支持              |

### 模块系统

| 模块系统            | 支持状态 | 备注         |
| --------------- | ---- | ---------- |
| ES Module (ESM) | ✅    | 推荐使用       |
| CommonJS (CJS)  | ✅    | 完整支持       |
| UMD             | ✅    | 适用于浏览器直接引入 |

## 网络请求库兼容性

| 库/API          | 自动追踪 | 手动追踪 | 备注                     |
| -------------- | ---- | ---- | ---------------------- |
| Fetch API      | ✅    | ✅    | 需要启用自动追踪配置             |
| XMLHttpRequest | ✅    | ✅    | 需要启用自动追踪配置             |
| Axios          | ✅    | ✅    | 通过拦截器自动追踪              |
| jQuery.ajax    | ⚠️   | ✅    | 基于 XMLHttpRequest，需要配置 |

## Web API 依赖

SDK 依赖以下 Web API，请确保目标浏览器支持：

### 必需的 API

| API                    | 用途        | 回退方案         |
| ---------------------- | --------- | ------------ |
| `navigator.sendBeacon` | 页面卸载时发送数据 | 使用 Fetch API |
| `fetch`                | 数据上报      | 无            |
| `Promise`              | 异步处理      | 无            |
| `JSON`                 | 数据序列化     | 无            |

### 可选的 API

| API                           | 用途        | 缺失时的影响      |
| ----------------------------- | --------- | ----------- |
| `PerformanceObserver`         | 性能监控      | 部分性能指标不可用   |
| `PerformanceNavigationTiming` | 导航性能数据    | 无法获取导航性能指标  |
| `PerformanceResourceTiming`   | 资源加载性能数据  | 无法获取资源性能指标  |
| `IntersectionObserver`        | 元素可见性检测   | 部分用户行为追踪受影响 |
| `MutationObserver`            | DOM 变化监控  | 部分自动追踪功能受影响 |
| `PerformanceLongTaskTiming`   | 长任务检测     | 无法检测长任务     |
| `visibilitychange` 事件         | 页面可见性变化检测 | 部分会话追踪功能受影响 |

## TypeScript 支持

| TypeScript 版本 | 支持状态 | 备注          |
| ------------- | ---- | ----------- |
| 4.0+          | ✅    | 提供完整类型定义    |
| 3.8 - 3.9     | ⚠️   | 基本支持，部分类型受限 |
| \< 3.8        | ❌    | 不支持         |

SDK 提供完整的 TypeScript 类型定义文件（`.d.ts`），支持智能提示和类型检查。

## 内容安全策略（CSP）

如果您的网站使用了 CSP，需要在 CSP 策略中添加以下配置：

```http CSP 配置 theme={null}
Content-Security-Policy:
  connect-src 'self' https://rum-intake.flashcat.cloud;
  script-src 'self' 'unsafe-inline';
```

<Note>
  如果使用 CDN 方式接入，还需要在 `script-src` 中添加 `https://static.flashcat.cloud`。
</Note>

## 隐私和安全

### Cookie 使用

SDK 可能使用以下类型的存储：

| 存储类型           | 用途        | 是否必需 |
| -------------- | --------- | ---- |
| localStorage   | 会话状态持久化   | 可选   |
| sessionStorage | 临时会话数据    | 可选   |
| Cookie         | 用户标识（可配置） | 可选   |

可以通过配置禁用 Cookie 和本地存储，使用纯内存模式。

### SameSite Cookie

SDK 默认使用 `SameSite=Lax` 策略，兼容现代浏览器的隐私要求。

## 已知限制

<AccordionGroup>
  <Accordion title="Safari 限制">
    | 限制项            | 说明                          |
    | -------------- | --------------------------- |
    | **长任务检测**      | Safari 不支持 Long Tasks API   |
    | **Web Vitals** | 仅支持 FID，不支持 CLS 和 LCP 的完整测量 |
    | **资源大小信息**     | 部分资源大小信息可能不准确               |
    | **页面隐藏时数据发送**  | iOS Safari 页面隐藏时无法保证数据立即发送  |
  </Accordion>

  <Accordion title="Firefox 限制">
    | 限制项            | 说明                           |
    | -------------- | ---------------------------- |
    | **长任务检测**      | Firefox 不支持 Long Tasks API   |
    | **浏览器干预检测**    | Firefox 不支持 Intervention API |
    | **Web Vitals** | 仅支持 FID                      |
  </Accordion>

  <Accordion title="移动浏览器限制">
    * **后台运行限制** - 移动浏览器在后台时可能暂停 JavaScript 执行
    * **内存限制** - 移动设备内存受限，可能影响数据缓存能力
    * **网络限制** - 移动网络不稳定可能导致数据上报延迟
  </Accordion>

  <Accordion title="单页应用（SPA）">
    * 需要启用路由变化追踪配置
    * 某些框架的路由库需要额外配置
    * 建议手动调用 `startView` 方法追踪路由变化

    <Tip>
      请参阅 [高级配置](/zh/rum/sdk/web/advanced-config#覆盖默认-rum-视图名称) 了解 SPA 路由追踪的详细配置。
    </Tip>
  </Accordion>
</AccordionGroup>

## 性能影响

FlashCat Web SDK 设计为轻量级，对网页性能的影响极小：

* **SDK 大小**：约 30 KB（gzip 后约 10 KB）
* **运行时内存占用**：\< 2 MB
* **CPU 占用**：\< 1%
* **首次加载影响**：\< 50ms

## 更新策略

* **主版本更新**：可能包含不兼容的更改，需要代码调整
* **次版本更新**：新增功能，向后兼容
* **补丁版本更新**：bug 修复，完全向后兼容

建议定期更新 SDK 到最新稳定版本以获得最佳性能和安全性。

## 最低部署要求

为了确保 SDK 正常工作，请确保：

1. **浏览器版本**：

   * Chrome 63+
   * Firefox 67+
   * Safari 12.1+
   * Edge 79+

2. **JavaScript 支持**：ES6+ (ES2015)

3. **必需的 Web API**：

   * `fetch` API
   * `Promise`
   * `JSON`

4. **网络访问**：应用需要能够访问 `https://rum-intake.flashcat.cloud` 以上报数据

5. **HTTPS**：推荐在 HTTPS 环境下使用以获得完整功能支持

## 相关文档

<CardGroup cols={3}>
  <Card title="SDK 接入指南" icon="plug" href="/zh/rum/sdk/web/sdk-integration">
    了解如何集成 SDK
  </Card>

  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/web/advanced-config">
    了解 SDK 的高级配置选项
  </Card>

  <Card title="数据收集" icon="database" href="/zh/rum/sdk/web/data-collection">
    了解 SDK 收集哪些数据
  </Card>
</CardGroup>