# @grafana/faro-instrumentation-replay 中文文档

规范地址：https://npmcn.com/package/%40grafana/faro-instrumentation-replay/

版本：2\.14\.0
npm 元数据更新时间：2026-11-09T16:00:01.434Z
中文译文更新时间：2026-11-16T21:46:16.127Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40grafana/faro-instrumentation-replay
原文对照：https://npmcn.com/package/%40grafana/faro-instrumentation-replay/?lang=original
项目主页：https://github.com/grafana/faro-web-sdk
源码仓库：https://github.com/grafana/faro-web-sdk

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

- 包体积（解压后）：1.4 MB，36 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-12-16T16:38:45.116Z
- 最新版本发布：2026-11-09T16:00:01.050Z
- 近 30 天下载量：232403（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

用 rrweb 重放会话的法罗仪器

## 安装

```sh
npm install @grafana/faro-instrumentation-replay
```

也可以使用：`pnpm add @grafana/faro-instrumentation-replay`、`yarn add @grafana/faro-instrumentation-replay`、`bun add @grafana/faro-instrumentation-replay`

## README

# @grafana/faro-instrumentation-replay (英语)

用 rrweb 重放会话的法罗仪表 .

不支持 Canvas 2D 和 WebGL 内容抓取 。 Canvas 元素可以出现在 记录的 DOM ,但不支持重放其绘图内容.

## 安装

```bash
npm install @grafana/faro-instrumentation-replay
```

## 使用量

```typescript
import { ReplayInstrumentation } from '@grafana/faro-instrumentation-replay';
import { getWebInstrumentations, initializeFaro } from '@grafana/faro-web-sdk';

initializeFaro({
  url: 'https://your-faro-endpoint.com',
  instrumentations: [
    ...getWebInstrumentations(),
    new ReplayInstrumentation({
      maskInputOptions: {
        password: true,
        email: true,
      },
      maskAllInputs: false,
      recordAfter: 'load',
      recordCrossOriginIframes: false,
    }),
  ],
});
```

## 配置选项

### 隐私和遮盖选项

| 密钥 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `sanitizeMetaHref` | `boolean` | `true` | 脱去证书、查询字符串和碎片 `window.location.href` 在 rrweb Meta 事件之前发送。 URL仍然可能在传输元数据和 DOM 快照中出现 |
| `maskAllInputs` | `boolean` | `true` | 覆盖所有输入内容 |
| `maskInputOptions` | `MaskInputOptions` | `{ password: true }` | 选择性地遮盖特定输入类型(仅在 `maskAllInputs` 实值 `false`(中文(简体) ) |
| `maskInputFn` | `(value: string, element: HTMLElement) => string` | 固定长度 `'******'` | 自定义口罩输入内容记录逻辑 。 默认返回一个固定长口罩,而不论输入长度,以防止长度泄漏 |
| `maskTextSelector` | `string` | `'*'` | CSS 文本内容应当被遮蔽的元素选择器 |
| `maskTextFn` | `(text: string, element: HTMLElement | null) => string` | `undefined` | 转换文本与匹配 `maskTextSelector` 或者说 `grafana-mask`。省略时,rrweb将非空白字符替换为 `*` |
| `blockSelector` | `string` | `undefined` | CSS选取器,用于应被屏蔽无法录入的元素. 被屏蔽的元素被相同尺寸的占位符所取代 |
| `ignoreSelector` | `string` | `undefined` | 输入事件应忽略的元素 CSS 选择器 |

#### 已建CSS课程

这些课程没有配置, 仍然与自定义选择器一起活动 :

| 类 | 行为 |
| --- | --- |
| `grafana-mask` | 元素及其后人中的遮盖文本,而不是输入值或属性. |
| `grafana-block` | 排除子树的内容,取而代之的是布局占位符. |
| `grafana-ignore` | 在匹配的输入、文本区或选择上禁止输入更改记录. |

```html
<span class="grafana-mask">Jane Doe</span>
<div class="grafana-block">Sensitive content</div>
<input class="grafana-ignore" type="search" />
```

#### `maskInputOptions`

| 密钥 | 类型 | 说明 |
| --- | --- | --- |
| `password` | `boolean` | 密码输入 |
| `text` | `boolean` | 文本输入 |
| `email` | `boolean` | 电子邮件输入 |
| `tel` | `boolean` | 电话投入 |
| `number` | `boolean` | 投入数量 |
| `search` | `boolean` | 搜索输入 |
| `url` | `boolean` | URL 输入 |
| `date` | `boolean` | 日期投入 |
| `datetime-local` | `boolean` | 日期-当地投入 |
| `month` | `boolean` | 月份投入 |
| `week` | `boolean` | 周投入 |
| `time` | `boolean` | 时间投入 |
| `color` | `boolean` | 颜色输入 |
| `range` | `boolean` | 范围输入 |
| `textarea` | `boolean` | 文本区域元素 |
| `select` | `boolean` | 选择下拉 |

### 记录选项

| 密钥 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `samplingRate` | `number` | `1` | 将记录的全球抽样会议。 应用于顶端 `sessionTracking.samplingRate`。外部值被夹住. |
| `recordAfter` | `'load' | 'DOMContentLoaded'` | `'load'` | 如果文档尚未准备好, 何时开始录制 |
| `recordCrossOriginIframes` | `boolean` | `false` | 是否记录跨源地的 Iframes 。 rrweb 必须在每个孩子的框中注入此功能 |
| `collectFonts` | `boolean` | `false` | 是否收集网站使用的字体 |
| `inlineImages` | `boolean` | `false` | 是否记录图像内容 |
| `inlineStylesheet` | `boolean` | `false` | 是否将样式表内入记录事件 |
| `inactivityThresholdMs` | `number` | `60000` | 在这多毫秒的无活性后暂停录入;在下个交互上自动恢复. 设定为 `0` 无法禁用 |

初始化后,a `ReplayInstrumentation` 实例也可以控制 明确使用 `pauseRecording()` 财务报告和审定财务报表 `resumeRecording()`恢复开始 a 新的 rrweb 记录, 并有一个新的 DOM 检查站。 明确暂停的录音 暂停至 `resumeRecording()` 名为.

#### 子样本示例

```typescript
initializeFaro({
  url: 'https://your-faro-endpoint.com',
  sessionTracking: {
    samplingRate: 1.0, // collect telemetry (logs, errors, web-vitals) for all sessions
  },
  instrumentations: [
    ...getWebInstrumentations(),
    new ReplayInstrumentation({
      samplingRate: 0.1, // record replay for only 10% of sessions
    }),
  ],
});
// Effective replay coverage: 1.0 × 0.1 = 10% of globally-sampled sessions
```

### 钩子

| 密钥 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `beforeSend` | `(event: eventWithTime) => eventWithTime | null | undefined` | `undefined` | 在发送前转换或过滤事件 。 返回时 `null` 或者说 `undefined` 要跳过发送 |

## 隐私和安全

此仪器记录了您的网站上的用户互动 。 确保:

1.  **检查您的掩码选项** - 默认情况下,所有输入值和文本内容都会被掩盖. 如果需要的话,你可以让面具更有选择性 `maskAllInputs`, (中文(简体) ), `maskInputOptions`,以及 `maskTextSelector`
2.  **使用 CSS 选择器** - 使用( I) `maskTextSelector` 掩盖敏感内容, `blockSelector` 完全排除要素
3.  **执行过滤** - 用那个 `beforeSend` 发送前过滤或转换事件的钩头
4.  **审查您的隐私政策** - 确保会议录音有适当的用户同意
5.  **测试您的配置** - 核实记录中没有收集任何敏感信息

### 示例:高级隐私配置

```typescript
new ReplayInstrumentation({
  // Disable global input masking and use selective masking rules instead
  maskAllInputs: false,
  // Mask all text and email inputs, but allow number inputs
  maskInputOptions: {
    password: true,
    text: true,
    email: true,
    tel: true,
    textarea: true,
  },
  // Mask elements with specific CSS classes
  maskTextSelector: '.sensitive-data, .pii',
  // Block elements completely from recording
  blockSelector: '.payment-form, .credit-card-info',
  // Ignore certain elements (won't be recorded at all)
  ignoreSelector: '.analytics-widget',
});
```

## 常见问题

### @grafana/faro-instrumentation-replay 是什么？

用 rrweb 重放会话的法罗仪器

### 如何安装 @grafana/faro-instrumentation-replay？

在项目目录运行 npm install @grafana/faro-instrumentation-replay，或使用 pnpm add / yarn add / bun add。

### @grafana/faro-instrumentation-replay 支持 TypeScript 吗？

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

### @grafana/faro-instrumentation-replay 支持 ESM 还是 CommonJS？

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

### @grafana/faro-instrumentation-replay 可以商用吗？

@grafana/faro-instrumentation-replay 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @grafana/faro-instrumentation-replay 的下载量有多少？

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

### @grafana/faro-instrumentation-replay 还在维护吗？

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

