本指南帮助您解决 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>
检查控制台
打开浏览器开发者工具（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 策略阻止 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 面板请求截图
- 问题复现步骤
相关文档
