Web SDK 问题排查

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

数据采集验证

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

SDK 安装检查

检查脚本引入

确认 RUM SDK 是否正确引入：

<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>

import { flashcatRum } from "@flashcatcloud/browser-rum";

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

检查控制台

打开浏览器开发者工具（F12），查看 Console 面板是否有 JavaScript 报错。

验证配置

确认应用 ID 和客户端令牌是否与 RUM 控制台中的配置一致。

网络请求检查

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

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

浏览器兼容性

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

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

广告拦截器影响

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

常见问题解决

数据未显示

问题：已完成 SDK 配置，但平台上没有数据。解决方案：

等待数据同步：数据一般在 2-5 分钟内显示
检查初始化时机：确保 SDK 在页面加载时就完成初始化
检查采样率：确认采样率设置合理

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

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

flashcatRum.setTrackingConsent("granted");

行为数据缺失

问题：用户行为数据不完整。解决方案：

启用行为跟踪：

flashcatRum.init({
  // ... 其他配置
  trackUserInteractions: true
});

为自定义元素添加标记：

<button data-action-name="提交表单">提交</button>

手动记录复杂交互：

flashcatRum.addAction("click", "自定义按钮点击");

异常数据缺失

问题：JavaScript 异常未被记录。解决方案：

启用异常跟踪：

flashcatRum.init({
  // ... 其他配置
  trackErrors: true
});

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

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

配置 Source Map：便于定位生产环境的问题，详见 Source Mapping

性能影响担忧

问题：担心 RUM SDK 影响网站性能。解决方案：

只启用必要的功能：

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

调整采样率：

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

过滤非关键资源：

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

CSP 配置问题

问题：CSP 策略阻止 RUM SDK 运行。解决方案：在您的 CSP 配置中添加以下规则：

script-src 'self' https://static.flashcat.cloud;
connect-src 'self' https://browser.flashcat.cloud;

单页应用页面访问未记录

问题：SPA 应用的路由切换未被记录。解决方案：

React Router
Vue Router
手动记录

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>
  );
}

router.afterEach((to) => {
  flashcatRum.startView({
    name: to.name || to.path,
    url: to.fullPath
  });
});

// 路由变化时调用
flashcatRum.startView({
  name: "商品详情页",
  url: "/products/123"
});

高级调试

启用调试模式

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

flashcatRum.init({
  // ... 其他配置
  debug: true
});

强制数据采集

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

flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 100,
  sessionReplaySampleRate: 100
});

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

控制台调试命令

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

// 获取 RUM 内部上下文
window.FC_RUM.getInternalContext();

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

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

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

网络请求分析

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

常见问题解答

数据多久能在平台显示？

一般在 2-5 分钟内显示，高峰期可能稍有延迟。

移动端浏览器是否支持？

支持 iOS Safari 和 Android Chrome 等主流移动端浏览器，但部分高级功能（如 Long Tasks 监控）可能受限。

如何排除特定页面的监控？

可以根据 URL 条件判断是否初始化：

// 排除管理后台页面
if (!window.location.pathname.startsWith("/admin")) {
  flashcatRum.init({
    // ... 配置
  });
}

如何跟踪多个子域名的用户？

需要以下配置：

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

flashcatRum.init({
  // ... 其他配置
  allowedTracingUrls: [
    "https://example.com",
    "https://app.example.com",
    "https://shop.example.com"
  ]
});

如何减少数据量和费用？

可以通过以下方式：

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

联系技术支持

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

准备诊断信息

请收集以下信息：

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

联系支持

邮箱：support@flashcat.cloud
在线咨询：点击平台右下角「帮助」按钮

SDK 接入指南

了解如何快速接入 RUM SDK

高级配置

了解 SDK 的高级配置功能

兼容性

了解浏览器和框架兼容性

快速开始

分析看板

SDK 接入

性能监控

异常追踪

查看器

会话重放

最佳实践

其他

数据采集验证

SDK 安装检查

网络请求检查

浏览器兼容性

广告拦截器影响

常见问题解决

高级调试

启用调试模式

强制数据采集

控制台调试命令

网络请求分析

常见问题解答

联系技术支持

相关文档

SDK 接入指南

高级配置

兼容性

​数据采集验证

​SDK 安装检查

​网络请求检查

​浏览器兼容性

​广告拦截器影响

​常见问题解决

​高级调试

​启用调试模式

​强制数据采集

​控制台调试命令

​网络请求分析

​常见问题解答

​联系技术支持

​相关文档

SDK 接入指南

高级配置

兼容性

数据采集验证

SDK 安装检查

网络请求检查

浏览器兼容性

广告拦截器影响

常见问题解决

高级调试

启用调试模式

强制数据采集

控制台调试命令

网络请求分析

常见问题解答

联系技术支持

相关文档