devlab-web-skywalking-rum-usage

devlab-frontend-skywalking-rum-usage

为前端应用接入 SkyWalking RUM（Real User Monitoring），实现 JS 错误监控、API 调用监控、Core Web Vitals 采集、SPA 路由感知和前后端分布式链路追踪。

本 Skill 负责浏览器性能/RUM 和浏览器链路；前端错误聚合、Source Map 与 Issue 管理统一走 infra-glitchtip-ops。完整支柱路由可选参考 devlab-observability-onboard 的 REFERENCE-ROUTE-TABLE.md。

适用场景

• 为前端应用安装并配置 skywalking-client-js
• 接入全局 JS 错误捕获（适配各前端框架）
• 采集 Core Web Vitals（LCP / CLS / INP）
• 监控 XHR / Fetch / Axios 等 API 调用的延迟和错误率
• SPA 路由切换时上报 PV 和性能数据
• 通过 sw8 header 实现浏览器→后端的分布式 trace 关联

不适用场景

• SkyWalking OAP 部署/升级/运维 → 使用 infra-skywalking-ops
• 后端 Java Agent 接入 → 使用 devlab-srv-skywalking-usage
• 前端错误聚合平台（Source Map / Issue 管理） → 使用 infra-glitchtip-ops
• OAP REST 端口反代配置 → 使用 infra-ingress-ops

前置条件

• SkyWalking OAP 版本 ≥ 10.2.0（Browser API 必须）
• OpenResty 已配置 RUM 反代（/browser/perfData/ → OAP REST :12800），含 CORS
• 前端项目可使用 npm 安装依赖

工作顺序

1. 安装 SDK

npm install skywalking-client-js --save

2. 初始化配置

在项目入口文件中初始化 SDK。参数通过环境变量注入，禁止硬编码。

// src/monitor/skywalking-rum.ts
import ClientMonitor from 'skywalking-client-js';

export function initRum(options: {
  collector: string;   // OpenResty HTTPS 反代地址，如 https://rum.{base_domain}
  service: string;     // 应用标识，如 'my-app-web'
  version: string;     // 应用版本号，如 'v1.0.0'
}) {
  ClientMonitor.register({
    collector: options.collector,
    service: options.service,
    serviceVersion: options.version,
    pagePath: location.pathname,
    jsErrors: true,          // JS 运行时错误
    apiErrors: true,         // API 调用错误（XHR/Fetch/Axios/SuperAgent）
    resourceErrors: true,    // 资源加载错误（图片/脚本/样式）
    useWebVitals: true,      // Core Web Vitals（LCP/CLS/INP）
    enableSPA: true,         // SPA hashchange 自动 PV 上报
    noTraceOrigins: [/localhost/, /127\.0\.0\.1/], // 开发环境排除
    traceTimeInterval: 60000, // 上报间隔（ms）
  });
}

环境变量配置示例：

框架	环境变量前缀	示例
Vite	VITE_	VITE_SW_COLLECTOR=https://rum.{base_domain}
Next.js	NEXT_PUBLIC_	NEXT_PUBLIC_SW_COLLECTOR=...
Create React App	REACT_APP_	REACT_APP_SW_COLLECTOR=...
Vue CLI	VUE_APP_	VUE_APP_SW_COLLECTOR=...