# @arms/rum-browser 中文文档

规范地址：https://npmcn.com/package/%40arms/rum-browser/

版本：0\.1\.18
npm 元数据更新时间：2026-10-27T13:36:19.643Z
中文译文更新时间：2026-11-06T19:55:28.955Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arms/rum-browser
原文对照：https://npmcn.com/package/%40arms/rum-browser/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，246 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@babel/runtime ^7\.24\.5
- 首次发布：2023-11-02T07:08:46.178Z
- 最新版本发布：2026-10-27T13:36:18.988Z
- 近 30 天下载量：232707（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 19 个）

## 中文简介

用于浏览器的朗姆酒

## 安装

```sh
npm install @arms/rum-browser
```

也可以使用：`pnpm add @arms/rum-browser`、`yarn add @arms/rum-browser`、`bun add @arms/rum-browser`

## README

# @arms/rum-browser

阿里云 ARMS 用户体验监控 Web & H5 SDK。覆盖页面 PV、性能（含 Web Vitals）、JS 异常、白屏、API（XHR/Fetch/SSE）、用户交互、视图停留与滚动深度、会话回放、Profiling CPU 采集等监控数据，支持分布式链路追踪，并提供产品分析能力（用户身份识别与业务行为 / 元素曝光采集）。

## 核心特性

-   **零配置即用**：一次 `init()` 后默认启用 PV / 性能 / Web Vitals / 异常 / API / 静态资源 / 点击 / 视图统计 / 白屏等采集器，无需逐项开关
-   **统一上报通道**：批量缓冲 + 失败重试，页面隐藏或卸载时自动完成最终上报，BFCache 与移动端切后台不丢数据
-   **API 监控全覆盖**：
    -   XHR / Fetch 全局 patch，自动产出 `type='api'` 资源事件
    -   SSE 流式接口（`text/event-stream`）独立子采集器，输出 `time_to_first_token` / `inter_token_latency_avg` / `inter_token_latency_max` / `message_count` 等指标
    -   `evaluateApi` 回调把请求/响应内容写入 `snapshots`，SDK 自动裁剪至 5KB
-   **视图维度增强**：`view-stats` 采集器输出页面停留时长（`time_spent`）、最大滚动深度、离开页面时的窗口尺寸
-   **产品分析（Product Analytics）**：登录后 `setUser()` 把业务账号关联到 SDK 匿名用户 ID，并自动回填登录前的匿名行为区间；通过 `data-rum-action` / `data-rum-expose` 声明式采集点击与曝光，或调用 `sendAction()` 手动上报业务行为；身份事件不受会话采样影响。详见 [`docs/Product-Analytics开发指南.md`](https://npmcn.com/package/%40arms/rum-browser/docs/Product-Analytics%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97.md)
-   **会话回放**：集成 `rrweb` 录制全量 DOM 与用户交互，支持 `mask` / `user-input` / `allowlisted` 隐私级别，长会话上报体积通过 deflate 压缩 60%~80%
-   **Profiling CPU 采集**：基于 W3C JS Self-Profiling API（仅 Chrome 系），支持后台自动采样与 `armsRum.startProfiling()` 手动采集；自动采集默认限会话开启后前 1 小时（`maxRecordingDuration` 可调），详见 [`docs/SDK配置参考.md`](https://npmcn.com/package/%40arms/rum-browser/docs/SDK%E9%85%8D%E7%BD%AE%E5%8F%82%E8%80%83.md)。⚠️ 目前为测试阶段能力，请谨慎开启
-   **分布式链路追踪**：内置 `tracing` 配置，支持 W3C tracecontext / B3 / B3 multi / Jaeger / SkyWalking sw8 协议，按 `allowedUrls` 白名单注入 `traceparent` 等头
-   **远程配置**：支持 ARMS 控制台下发配置，动态调整采样率、采集器开关、过滤规则

## 安装

提供 CDN 异步 / CDN 同步 / NPM 三种接入方式，详见 [`docs/接入Web&H5应用.md`](https://npmcn.com/package/%40arms/rum-browser/docs/%E6%8E%A5%E5%85%A5Web&H5%E5%BA%94%E7%94%A8.md)。

另提供精简版：CDN 产物 `https://sdk.rum.aliyuncs.com/v2/browser-sdk-slim.js`（约 124KB，比完整版小约 63%），NPM 方式可通过子路径 `@arms/rum-browser/slim` 引入。不需要会话回放、白屏检测与 Profiling 采集时可选用，用法与完整版一致，详见 [`docs/接入Web&H5应用.md`](https://npmcn.com/package/%40arms/rum-browser/docs/%E6%8E%A5%E5%85%A5Web&H5%E5%BA%94%E7%94%A8.md)。

```bash
npm install @arms/rum-browser
```

| 依赖 | 版本要求 | 说明 |
| --- | --- | --- |
| 浏览器 | Chrome / Safari / Firefox / Edge 最近 2 个大版本 | 不再支持 IE |
| `@babel/runtime` | `^7.24.5` | `peerDependency`，由业务侧安装 |

## 接入流程

### 第一步：在应用入口尽早 import SDK

`init()` 务必在业务发起任何 XHR / Fetch 请求**之前**调用——SDK 通过代理 `window.fetch` / `XMLHttpRequest` 实现 API 采集，初始化之前发出的请求采不到。

```typescript
// src/main.ts
import armsRum from '@arms/rum-browser';

armsRum.init({
  endpoint: '<your-endpoint>',
  env: 'prod',
  version: '1.0.0',
});
```

### 第二步：CDN 接入（首屏敏感场景推荐）

将以下片段放在 `<head>` 中尽可能靠前的位置，SDK 异步加载完成后会自动从 `window.__rum.config` 读取配置启动：

```html
<script>
  !(function (c, b, d, a) {
    c[a] || (c[a] = {});
    c[a].config = {
      endpoint: '<your-endpoint>',
      env: 'prod',
      version: '1.0.0',
    };
    with (b)
      with (body)
        with (insertBefore(createElement('script'), firstChild))
          setAttribute('crossorigin', '', (src = d));
  })(
    window,
    document,
    'https://sdk.rum.aliyuncs.com/v2/browser-sdk.js',
    '__rum',
  );
</script>
```

### 第三步：（可选）验证数据上报

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  beforeReport(bundle) {
    console.log('[RUM]', bundle);
    return bundle; // 返回 undefined 不会丢弃；如需丢弃需在回调里显式处理
  },
});
```

### 第四步：（可选）启用 SPA 路由追踪

单页应用必须显式声明 `spaMode`，否则路由切换不会被视作新页面：

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  spaMode: 'history', // 'hash' | 'history' | 'auto' | true | false
});
```

### 第五步：（可选）启用会话回放

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  replay: {
    enable: true,
    sampling: 20, // 20% 会话录制（百分比，0~100）
    privacy: { level: 'mask' }, // 默认遮蔽所有文本与输入框
  },
});
```

### 第六步：（可选）启用产品分析（用户身份 + 业务行为）

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  collectors: { expose: true }, // 曝光采集默认关闭，按需开启
});

// 登录成功后关联业务账号（身份状态持久化，刷新后保持登录态）
armsRum.setUser({ name: 'u_10086', properties: { plan: 'pro' } });
```

```html
<!-- 声明式点击 / 曝光：元素上加 data-rum-action / data-rum-expose -->
<button data-rum-action="加入购物车" data-rum-prop-sku="A1">加入购物车</button>
<div data-rum-expose data-rum-action="商品卡片">…</div>
```

详见 [`docs/Product-Analytics开发指南.md`](https://npmcn.com/package/%40arms/rum-browser/docs/Product-Analytics%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97.md)。

## 配置项

`init()` 接收 `IBrowserConfig` 配置对象。下表只列出常用字段，完整版见 [`docs/SDK配置参考.md`](https://npmcn.com/package/%40arms/rum-browser/docs/SDK%E9%85%8D%E7%BD%AE%E5%8F%82%E8%80%83.md)。

### 基础配置

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `endpoint` | `string` | 是 | — | ARMS 数据上报地址 |
| `enable` | `boolean` | 否 | `true` | 关闭后所有采集器与上报均不工作 |
| `env` | `'prod' | 'gray' | 'pre' | 'daily' | 'local' | string` | 否 | — | 应用环境标识 |
| `version` | `string` | 否 | — | 应用版本号 |
| `app` | `object` | 否 | — | 应用扩展信息（`name` / `channel` / `framework` 等） |

> **说明** 用户 ID（`user.id`）由 SDK 内部自动生成并持久化，不可通过配置传入或修改，上报数据中可直接按 `user.id` 做用户维度排查。业务账号可通过 `user.name` / `user.properties` 配置项或 `armsRum.setUser()` 等 API 关联（产品分析能力，详见 [`docs/Product-Analytics开发指南.md`](https://npmcn.com/package/%40arms/rum-browser/docs/Product-Analytics%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97.md)）。

### Web 专属配置

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `spaMode` | `false | true | 'auto' | 'hash' | 'history'` | `false` | SPA 路由追踪模式 |
| `replay` | `boolean | IReplayOption` | `false` | 会话回放配置 |
| `tracing` | `boolean | ITracingOption` | — | 分布式链路追踪配置（XHR / Fetch / SSE 共用） |
| `evaluateApi` | `(request, response, error?, xhr?) => Promise<IApiAttr>` | — | 自定义 API 事件解析回调，返回值由 SDK 裁剪后合并到事件 |
| `parseViewName` | `(url: string) => string` | — | 自定义页面 name 解析 |
| `parseResourceName` | `(url: string) => string` | — | 自定义资源 name 解析（默认取 URL pathname） |

### 采集器开关（collectors）

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  collectors: {
    consoleError: false, // 关闭 console.error 拦截
    longTask: true, // 默认关闭，按需启用
    profiling: false, // Profiling CPU 采集（测试阶段能力，谨慎开启）
    expose: { enable: true, threshold: 0.5, minDuration: 500 }, // 曝光采集（默认关闭）
    api: {
      // API 采集器细化配置
      enable: true,
      filters: [/\.internal\.example\.com/], // 命中则不上报
      xhr: true,
      fetch: true,
      sse: { timeout: 30000 }, // SSE 流 30s 无消息判超时
    },
  },
});
```

| 采集器 | 默认 | 说明 |
| --- | --- | --- |
| `jsError` | `true` | 未捕获异常 + 未处理 Promise 拒绝 |
| `consoleError` | `true` | `console.error` 拦截上报 |
| `api` | `true` | XHR + Fetch + SSE 资源事件（`type='api'`） |
| `staticResource` | `true` | 静态资源加载（`type='resource'`） |
| `perf` | `true` | 页面加载性能 |
| `webVitals` | `true` | Web Vitals（LCP / FID / CLS） |
| `click` | `true` | 用户点击事件（含 `data-rum-action` 声明式点击） |
| `expose` | `false` | 元素曝光采集（`data-rum-expose`），按 view + 元素聚合有效曝光次数与累计可见时长，页面切换 / 隐藏时结算上报，按需开启 |
| `viewStats` | `true` | 视图停留时长 / 滚动深度（`type='view-stats'`） |
| `longTask` | `false` | 长任务（LoAF 优先，降级到 longtask `>50ms`），按需开启 |
| `profiling` | `false` | Profiling CPU 采集（W3C JS Self-Profiling，仅 Chrome 系，仅完整版），自动采集默认限会话开启后前 1 小时（`maxRecordingDuration` 可调），测试阶段能力，谨慎开启 |

### evaluateApi：自定义 payload 写入 snapshots

`evaluateApi` 用于把请求/响应内容写入事件，**SDK 不自动采集 payload**——业务侧按需在回调里提取并返回 `{ snapshots: string }`，SDK 自动裁剪至 5KB：

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  async evaluateApi(request, response, error, xhr) {
    const snapshot: Record<string, unknown> = {};
    // Fetch：response.clone().text() 读取
    if (response && typeof (response as Response).text === 'function') {
      try {
        const text = await (response as Response).clone().text();
        snapshot.response = text.slice(0, 1024);
      } catch {}
    }
    // XHR：直接读 xhr.responseText
    if (xhr) snapshot.response = xhr.responseText?.slice(0, 1024);

    return {
      success: error || (response as Response)?.status >= 400 ? 0 : 1,
      snapshots: JSON.stringify(snapshot),
    };
  },
});
```

> 字段约定：`snapshots` 留给 SDK / `evaluateApi` 写采集元数据，`properties` 保留给用户业务标签。

### 链路追踪（tracing）

```typescript
armsRum.init({
  endpoint: '<your-endpoint>',
  tracing: {
    enable: true,
    sample: 10, // 10% 采样（百分比）
    propagatorTypes: ['tracecontext', 'b3'],
    allowedUrls: [/^https:\/\/api\.example\.com/], // 仅向白名单注入追踪头
  },
});
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `enable` | `boolean` | 是否启用链路追踪 |
| `sample` | `number` | 采样率（0~100，百分比） |
| `propagatorTypes` | `Array<'tracecontext' | 'b3' | 'b3multi' | 'jaeger' | 'sw8'>` | 传播协议 |
| `allowedUrls` | `Array<MatchOption | TraceOption>` | 允许注入追踪头的 URL/path 规则 |
| `tracestate` / `baggage` | `boolean` | 是否携带 W3C tracestate / baggage |

XHR / Fetch / SSE 共用同一份 `tracing` 决策。`allowedUrls` 未配置时不会向任何 URL 注入追踪头——避免向第三方域名泄漏内部 traceId。

### 会话回放（replay）

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enable` | `boolean` | `false` | 是否启用 |
| `sampling` | `number` | `1` | 录制采样率（0~100，百分比）；默认仅录制 1% 会话，按需调高 |
| `url` | `string` | — | replay 数据上报地址（不指定则与主上报通道共享） |
| `privacy.level` | `'allow' | 'mask' | 'user-input' | 'allowlisted'` | `'mask'` | 隐私保护级别 |
| `privacy.allowlisted` | `any[]` | — | `level: 'allowlisted'` 时的允许录制元素选择器 |

> **录制时长上限** 单会话录制最长 1 小时，超时自动停止录制。生产环境务必配合 `sampling` 控制采样率。

## 运行时 API

```typescript
import armsRum, { sendEvent } from '@arms/rum-browser';

// 修改单个字段
armsRum.setConfig('enable', false);

// 批量修改
armsRum.setConfig({ env: 'staging', version: '1.1.0' });

// 读取当前完整配置
const config = armsRum.getConfig();

// 获取某个采集器实例（扩展 / 调试用）
const replay = armsRum.getCollector('replay-collector');

// 用户身份（产品分析）：登录 / 属性 / 退出
armsRum.setUser({ name: 'u_10086', properties: { plan: 'pro' } });
armsRum.setUserProperties({ vip: true });
armsRum.unsetUserProperties(['level', 'vip']);
armsRum.reset();

// 业务行为上报（如需表单提交成功、播放完成等非点击场景）
armsRum.sendAction({
  name: '提交订单',
  group: '结算',
  properties: { amount: 747 },
});

// 业务侧自定义事件上报（所有 SDK 实例都会收到）
sendEvent({
  event_type: 'custom',
  type: 'business-event',
  name: 'order-submit',
});
```

CDN 加载方式下，`sendEvent` 也可通过全局对象访问：`window.RumSDK.sendEvent(event)`。

> 产品分析完整 API（身份状态机、属性规则、匿名区间回填、曝光结算规则等）见 [`docs/Product-Analytics开发指南.md`](https://npmcn.com/package/%40arms/rum-browser/docs/Product-Analytics%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97.md)。

## 注意事项

1.  **`init()` 务必尽早执行**：SDK 通过代理 `window.fetch` / `XMLHttpRequest` 实现 API 采集，初始化之前发出的请求采不到。
2.  **CDN 异步加载 vs 同步加载**：异步加载不阻塞渲染，但 SDK 启动前的早期错误可能漏采；如对早期错误敏感，可在 `<head>` 顶部加临时 `window.onerror` / `unhandledrejection` 缓冲，SDK 启动后通过 `RumSDK.sendEvent()` 补报。
3.  **`spaMode` 必须与路由实现一致**：错配会导致 view 事件采到错误的 path（如把 React BrowserRouter 当成 hash）。
4.  **`evaluateApi` 内禁止同步阻塞**：回调如抛错会被静默捕获回退到原始事件；读取大 body 请用流式或限制大小，否则会拖慢上报队列。
5.  **`replay` 会显著增加上报量**：生产环境务必配合 `sampling` 控制采样率；隐私级别默认 `'mask'` 不要随意调成 `'allow'`。
6.  **`tracing.allowedUrls` 必须显式声明**：未配置时不会注入追踪头，避免向不可控第三方域名泄漏内部 traceId。
7.  **`longTask` 默认关闭**：长任务事件量大，按需开启；开启后优先用 LoAF，不支持时降级到 longtask（`>50ms`）。
8.  **产品分析身份与隐私**：`setUser` 的 `name` 建议使用稳定且不含个人敏感信息的业务 ID；身份状态持久化在本地（key：`_arms_pa_user:<pid>`），如涉及隐私合规请在退出时调用 `reset()`；曝光采集默认关闭（`collectors.expose`），元素需同时带 `data-rum-expose` 与非空 `data-rum-action` 才会采集。

## 常见问题

### @arms/rum-browser 是什么？

用于浏览器的朗姆酒

### 如何安装 @arms/rum-browser？

在项目目录运行 npm install @arms/rum-browser，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@babel/runtime（^7\.24\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @arms/rum-browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arms/rum-browser 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @arms/rum-browser 可以商用吗？

@arms/rum-browser 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @arms/rum-browser 的下载量有多少？

根据 npm 官方下载统计，@arms/rum-browser 在 2026/10/07 – 2026/11/05 这 30 天内被下载 232,707 次，日均约 7,757 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arms/rum-browser 还在维护吗？

最新版本 0\.1\.18 发布于 2026/10/27（11 天前）；至今共发布 78 个版本，其中过去 12 个月发布了 19 个；首次发布于 2023/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。