前端框架插件接入¶

从 RUM SDK 3.3.6 开始，可以通过独立框架插件采集框架路由 View 和框架错误。框架插件与 RUM 主包保持独立，应用只需安装实际使用的插件。

支持范围¶

框架	支持版本	路由能力	错误能力
React	React 18、19；React Router 6、7、8；TanStack Router 1.x	使用路由模板命名 View，忽略仅 query 或 hash 变化	`ErrorBoundary`、`addReactError()`
Vue	Vue 2.7 + Vue Router 3；Vue 3 + Vue Router 4	使用匹配到的路由模板命名 View，忽略仅 query 变化	Vue 全局错误处理器、`addVueError()`
Angular	Angular 15 至 22；RxJS 7 及以上	在 `NavigationEnd` 后启动 View，忽略取消、失败及仅 query 或 hash 变化	Angular `ErrorHandler`、`addAngularError()`
Next.js	Next.js 13 及以上、React 18 及以上	支持 App Router 和 Pages Router	参见 SSR 框架下接入
Nuxt	Nuxt 3、4；Vue 3；Vue Router 4	支持 Nuxt 文件路由和客户端导航	参见 SSR 框架下接入

版本要求

RUM 主包版本不得低于框架插件版本。一个应用只能初始化完整 RUM 包或精简 RUM 包中的一个，不要同时初始化两个 RUM 实例。

完整 RUM 包支持 Session Replay 和压缩上报；精简 RUM 包不包含这两项能力。两种 RUM 包均可使用框架插件采集 View 与 Error。

使用精简 RUM 包时，只需要替换 RUM 导入，框架插件配置保持不变：

import { datafluxRum } from "@cloudcare/browser-rum-slim"

以下示例使用公网 OpenWay 的 site 和 clientToken。使用 DataKit 直连时，将这两个参数替换为 datakitOrigin，不要同时配置两种上报地址。

React¶

安装¶

npm install @cloudcare/browser-rum @cloudcare/browser-rum-react

React Router¶

启用 Router 集成时，需要：

在 reactPlugin() 中设置 router: true；
从与 React Router 主版本匹配的插件子路径导入 Router 创建 API、 Routes 或 useRoutes。

以下示例使用 React Router 6：

import { RouterProvider } from "react-router-dom"
import { datafluxRum } from "@cloudcare/browser-rum"
import { reactPlugin } from "@cloudcare/browser-rum-react"
import {
  createBrowserRouter,
} from "@cloudcare/browser-rum-react/react-router-v6"

const router = createBrowserRouter([
  { path: "/", element: <Home /> },
  { path: "/users/:id", element: <UserDetail /> },
])

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-react",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  plugins: [reactPlugin({ router: true })],
})

root.render(<RouterProvider router={router} />)

根据 Router 版本选择入口：

Router	插件入口	由插件入口导出的 API
React Router 6	`@cloudcare/browser-rum-react/react-router-v6`	`createBrowserRouter`、`createHashRouter`、`createMemoryRouter`、`Routes`、`useRoutes`
React Router 7	`@cloudcare/browser-rum-react/react-router-v7`	同上
React Router 8	`@cloudcare/browser-rum-react/react-router-v8`	同上
TanStack Router 1.x	`@cloudcare/browser-rum-react/tanstack-router`	`createRouter`

其他 Router API 仍从应用安装的 Router 包导入。不要从框架插件主入口导入 Router wrapper，否则插件无法区分 Router 主版本。

React 错误¶

在应用根节点或关键业务区域外层使用 ErrorBoundary：

import { ErrorBoundary } from "@cloudcare/browser-rum-react"

root.render(
  <ErrorBoundary
    fallback={({ resetError }) => (
      <button type="button" onClick={resetError}>重试</button>
    )}
    context={{ module: "checkout" }}
  >
    <App />
  </ErrorBoundary>
)

已有 ErrorBoundary、React 19 根节点错误回调或业务主动捕获错误时，调用 addReactError(error, errorInfo, context)。React Error 事件会包含 context.framework = react，存在组件栈时还会包含 context.component_stack。

Vue¶

安装¶

npm install @cloudcare/browser-rum @cloudcare/browser-rum-vue

Vue 3 与 Vue Router 4¶

import { createApp } from "vue"
import { createWebHistory } from "vue-router"
import { datafluxRum } from "@cloudcare/browser-rum"
import { vuePlugin } from "@cloudcare/browser-rum-vue"
import {
  createRouter,
} from "@cloudcare/browser-rum-vue/vue-router-v4"

const app = createApp(App)
const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: "/", component: Home },
    { path: "/users/:id", component: UserDetail },
  ],
})

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-vue",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  plugins: [vuePlugin({ app, router: true })],
})

app.use(router)
app.mount("#app")

传入 app 后，插件会安装 Vue 全局错误处理器，同时保留应用已有的 app.config.errorHandler。

Vue 2.7 与 Vue Router 3¶

import Vue from "vue"
import { datafluxRum } from "@cloudcare/browser-rum"
import { vuePlugin } from "@cloudcare/browser-rum-vue"
import VueRouter from "@cloudcare/browser-rum-vue/vue-router-v3"

Vue.use(VueRouter)
const router = new VueRouter({ routes })

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  plugins: [vuePlugin({ app: Vue, router: true })],
})

new Vue({ router, render: (h) => h(App) }).$mount("#app")

已有自定义错误处理器时，也可以调用 addVueError(error, componentInstance, info, context)。Vue Error 事件会包含 context.framework = vue，并尽可能记录组件名称和组件路径。

Angular¶

安装¶

npm install @cloudcare/browser-rum @cloudcare/browser-rum-angular

Standalone 应用¶

import { bootstrapApplication } from "@angular/platform-browser"
import { provideRouter } from "@angular/router"
import { datafluxRum } from "@cloudcare/browser-rum"
import { angularPlugin } from "@cloudcare/browser-rum-angular"
import {
  provideRumErrorHandler,
  provideRumRouter,
} from "@cloudcare/browser-rum-angular/providers"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-angular",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  plugins: [angularPlugin({ router: true })],
})

bootstrapApplication(AppComponent, {
  providers: [
    provideRouter(routes),
    provideRumRouter(),
    provideRumErrorHandler(),
  ],
})

provideRumRouter() 只在 Angular Router 成功触发 NavigationEnd 后启动 View。取消或失败的导航不会生成 View。provideRumErrorHandler() 在上报 Error 的同时，保留 Angular 默认的控制台错误处理行为。

已有自定义 ErrorHandler 时，可以调用 addAngularError(error, context)；已有自定义 Router 集成时，可以调用 trackAngularRouter(router)。

View 命名与生命周期¶

启用框架 Router 集成后，插件会接管手动 View：

场景	采集行为
首次进入路由	创建初始 View
pathname 变化且导航成功	创建新 View
仅 query 变化	不创建新 View
仅 hash 变化	React、Angular 不创建新 View；Nuxt 可跟踪 hash 路由
动态路由	使用 `/users/:id`、`/users/[id]` 等模板名称
跳转取消、失败或新页面未提交	不创建 View

不要同时使用 Router 插件和业务代码中的 datafluxRum.startView() 跟踪同一次路由，否则可能产生重复 View。

React、Vue 和 Angular 插件均支持 getViewName 回调。返回自定义字符串可覆盖默认路由模板；返回 undefined 会跳过当前路由的 View 创建。

验证接入¶

打开浏览器开发者工具，在 Network 中过滤 /v1/write/rum。
进入动态路由，例如从 /users/1 跳转到 /users/2。
确认 View 名称保持为路由模板，而不是具体用户 ID。
只修改 query，确认没有重复创建 View。
触发框架渲染错误，确认出现 type=error，并带有对应 context.framework。

常见问题¶

启用 `router: true` 后没有 View¶

确认 Router 创建 API、Routes 或 useRoutes 来自与当前 Router 主版本匹配的插件子路径。只注册插件但继续使用原始 Router 创建 API 时，插件无法获得完整路由状态。

一个路由跳转产生多个 View¶

确认应用没有重复注册 Router 插件，也没有为同一次路由变化额外调用 datafluxRum.startView()。

动态路由产生大量 View 名称¶

优先使用 Router 模板路径。无法从路由配置自动获得稳定名称时，通过 getViewName 把实体 ID 统一映射为固定业务名称。