> ## 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 使用过程中的常见问题，包括数据采集异常、SDK 配置和性能优化

<Info>
  本指南帮助您解决 Web RUM SDK 使用过程中可能遇到的常见问题，包括数据采集异常、SDK 配置问题和性能优化等方面。
</Info>

## 数据采集验证

如果您在 RUM 平台上看不到数据，请按以下步骤进行检查。

### SDK 安装检查

<Steps>
  <Step title="检查脚本引入">
    确认 RUM SDK 是否正确引入：

    <CodeGroup>
      ```html CDN 引入 theme={null}
      <script
        src="https://static.flashcat.cloud/browser-sdk/v0/flashcat-rum.js"
        type="text/javascript"
      ></script>
      <script>
        window.FC_RUM &&
          window.FC_RUM.init({
            applicationId: "您的应用ID",
            clientToken: "您的客户端令牌",
            service: "<SERVICE_NAME>",
            env: "<ENV_NAME>",
            version: "1.0.0",
            sessionSampleRate: 10
          });
      </script>
      ```

      ```javascript npm 引入 theme={null}
      import { flashcatRum } from "@flashcatcloud/browser-rum";

      flashcatRum.init({
        applicationId: "您的应用ID",
        clientToken: "您的客户端令牌",
        service: "<SERVICE_NAME>",
        env: "<ENV_NAME>",
        version: "1.0.0"
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="检查控制台">
    打开浏览器开发者工具（F12），查看 Console 面板是否有 JavaScript 报错。
  </Step>

  <Step title="验证配置">
    确认应用 ID 和客户端令牌是否与 RUM 控制台中的配置一致。
  </Step>
</Steps>

### 网络请求检查

1. 打开浏览器开发者工具的 **Network** 面板
2. 筛选 `browser.flashcat.cloud` 的请求
3. 确认请求状态码为 `200`
4. 如果请求失败，查看具体错误信息

<Warning>
  如果看到 CORS 错误，请检查您的 CSP 配置是否正确。
</Warning>

### 浏览器兼容性

确认您使用的浏览器版本是否受支持：

| 浏览器               | 最低版本       |
| ----------------- | ---------- |
| Chrome            | 60+        |
| Firefox           | 60+        |
| Safari            | 12+        |
| Edge              | 15+        |
| Internet Explorer | 11（部分功能受限） |

### 广告拦截器影响

<Note>
  部分广告拦截插件可能会阻止 RUM SDK 的运行。建议将您的域名和 `browser.flashcat.cloud` 加入白名单。
</Note>

## 常见问题解决

<AccordionGroup>
  <Accordion title="数据未显示">
    **问题**：已完成 SDK 配置，但平台上没有数据。

    **解决方案**：

    1. **等待数据同步**：数据一般在 2-5 分钟内显示

    2. **检查初始化时机**：确保 SDK 在页面加载时就完成初始化

    3. **检查采样率**：确认采样率设置合理

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      sessionSampleRate: 100  // 设为 100 表示采集所有会话
    });
    ```

    4. **检查用户授权**：确认用户跟踪授权状态

    ```javascript theme={null}
    flashcatRum.setTrackingConsent("granted");
    ```
  </Accordion>

  <Accordion title="行为数据缺失">
    **问题**：用户行为数据不完整。

    **解决方案**：

    1. **启用行为跟踪**：

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      trackUserInteractions: true
    });
    ```

    2. **为自定义元素添加标记**：

    ```html theme={null}
    <button data-action-name="提交表单">提交</button>
    ```

    3. **手动记录复杂交互**：

    ```javascript theme={null}
    flashcatRum.addAction("click", "自定义按钮点击");
    ```
  </Accordion>

  <Accordion title="异常数据缺失">
    **问题**：JavaScript 异常未被记录。

    **解决方案**：

    1. **启用异常跟踪**：

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      trackErrors: true
    });
    ```

    2. **手动上报 try-catch 中的异常**：

    ```javascript theme={null}
    try {
      // 可能出错的代码
    } catch (error) {
      console.error(error);
      flashcatRum.addError(error);
    }
    ```

    3. **配置 Source Map**：便于定位生产环境的问题，详见 [Source Mapping](/zh/rum/error-tracking/source-mapping)
  </Accordion>

  <Accordion title="性能影响担忧">
    **问题**：担心 RUM SDK 影响网站性能。

    **解决方案**：

    1. **只启用必要的功能**：

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      trackResources: true,
      trackLongTasks: false,  // 关闭不需要的功能
      trackErrors: true,
      trackUserInteractions: true
    });
    ```

    2. **调整采样率**：

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      sessionSampleRate: 50  // 只采集 50% 的会话
    });
    ```

    3. **过滤非关键资源**：

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      beforeSend: (event) => {
        // 过滤掉非关键资源
        if (event.type === 'resource' && event.resource.url.includes('/static/')) {
          return false;
        }
        return true;
      }
    });
    ```
  </Accordion>

  <Accordion title="CSP 配置问题">
    **问题**：CSP 策略阻止 RUM SDK 运行。

    **解决方案**：

    在您的 CSP 配置中添加以下规则：

    ```
    script-src 'self' https://static.flashcat.cloud;
    connect-src 'self' https://browser.flashcat.cloud;
    ```
  </Accordion>

  <Accordion title="单页应用页面访问未记录">
    **问题**：SPA 应用的路由切换未被记录。

    **解决方案**：

    <Tabs>
      <Tab title="React Router">
        ```javascript theme={null}
        import { useEffect } from "react";
        import { useLocation } from "react-router-dom";

        function RumRouteTracker() {
          const location = useLocation();

          useEffect(() => {
            flashcatRum.startView({
              name: location.pathname,
              url: location.pathname + location.search
            });
          }, [location]);

          return null;
        }

        // 在 App 组件中使用
        function App() {
          return (
            <Router>
              <RumRouteTracker />
              {/* 其他路由 */}
            </Router>
          );
        }
        ```
      </Tab>

      <Tab title="Vue Router">
        ```javascript theme={null}
        router.afterEach((to) => {
          flashcatRum.startView({
            name: to.name || to.path,
            url: to.fullPath
          });
        });
        ```
      </Tab>

      <Tab title="手动记录">
        ```javascript theme={null}
        // 路由变化时调用
        flashcatRum.startView({
          name: "商品详情页",
          url: "/products/123"
        });
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## 高级调试

### 启用调试模式

开启调试模式可在控制台获取详细日志：

```javascript theme={null}
flashcatRum.init({
  // ... 其他配置
  debug: true
});
```

### 强制数据采集

测试时可强制开启全量数据采集：

```javascript theme={null}
flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 100,
  sessionReplaySampleRate: 100
});
```

<Warning>
  请勿在生产环境使用 100% 采样率，以避免产生过多数据和费用。
</Warning>

### 控制台调试命令

在浏览器控制台中可使用以下命令：

```javascript theme={null}
// 获取 RUM 内部上下文
window.FC_RUM.getInternalContext();

// 获取当前会话 ID
window.FC_RUM.getSessionId();

// 获取当前页面 ID  
window.FC_RUM.getViewId();

// 手动发送测试事件
window.FC_RUM.addAction('test', 'debug_action');
```

### 网络请求分析

1. 打开开发者工具 **Network** 面板
2. 筛选 `browser.flashcat.cloud` 请求
3. 查看请求 Payload 确认数据内容
4. 检查 Response 确认上报成功

## 常见问题解答

<AccordionGroup>
  <Accordion title="数据多久能在平台显示？">
    一般在 2-5 分钟内显示，高峰期可能稍有延迟。
  </Accordion>

  <Accordion title="移动端浏览器是否支持？">
    支持 iOS Safari 和 Android Chrome 等主流移动端浏览器，但部分高级功能（如 Long Tasks 监控）可能受限。
  </Accordion>

  <Accordion title="如何排除特定页面的监控？">
    可以根据 URL 条件判断是否初始化：

    ```javascript theme={null}
    // 排除管理后台页面
    if (!window.location.pathname.startsWith("/admin")) {
      flashcatRum.init({
        // ... 配置
      });
    }
    ```
  </Accordion>

  <Accordion title="如何跟踪多个子域名的用户？">
    需要以下配置：

    1. 使用相同的应用 ID 和客户端令牌
    2. 设置一致的用户标识
    3. 启用跨域跟踪：

    ```javascript theme={null}
    flashcatRum.init({
      // ... 其他配置
      allowedTracingUrls: [
        "https://example.com",
        "https://app.example.com",
        "https://shop.example.com"
      ]
    });
    ```
  </Accordion>

  <Accordion title="如何减少数据量和费用？">
    可以通过以下方式：

    1. **降低采样率**：设置 `sessionSampleRate` 为 10-50
    2. **关闭不必要的功能**：如 `trackLongTasks: false`
    3. **排除特定页面**：不在管理后台等内部页面初始化
    4. **配置数据过滤**：使用 `beforeSend` 过滤非关键数据
  </Accordion>
</AccordionGroup>

## 联系技术支持

如果按上述步骤排查后仍有问题，请联系我们的技术支持团队。

<Steps>
  <Step title="准备诊断信息">
    请收集以下信息：

    * 应用 ID
    * 浏览器类型和版本
    * SDK 版本
    * 控制台错误截图
    * Network 面板请求截图
    * 问题复现步骤
  </Step>

  <Step title="联系支持">
    * **邮箱**：[support@flashcat.cloud](mailto:support@flashcat.cloud)
    * **在线咨询**：点击平台右下角「帮助」按钮
  </Step>
</Steps>

## 相关文档

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

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

  <Card title="兼容性" icon="browser" href="/zh/rum/sdk/web/compatible">
    了解浏览器和框架兼容性
  </Card>
</CardGroup>