rrweb 文档
rrwebDocs

简体中文

English

简体中文

English

rrweb ​

概述 ​

已弃用。 rrweb 仅为向后兼容而保留。新项目应直接依赖 @rrweb/record 和 @rrweb/replay，或使用 @rrweb/all 进行单次便捷导入。迁移到这些入口点能让我们精简并最终移除本包。

rrweb 意为 “record and replay the web”（录制并回放 Web），是一个用于录制和回放用户在 Web 上交互的工具。

在大多数生产环境中，录制器和回放器会部署到不同的页面/应用。请在被录制的页面使用 @rrweb/record，在回放页面使用 @rrweb/replay（或使用 rrweb-player 以包含 UI）。

使用场景包选择
大多数应用（显式声明录制/回放依赖）@rrweb/record + @rrweb/replay
通过一个导入获得录制、回放和 packer@rrweb/all

开发说明 ​

由于这是 rrweb 最初的包，@rrweb/record 和 @rrweb/replay 的 TypeScript 代码仍位于本包的 src/record 和 src/replay 目录中。这些代码日后会重构到各自的包中，但目前本包仍是录制和回放相关 PR 的主要包。更多信息请参阅 rrweb 贡献指南。

安装 ​

1) 打包器 / npm（推荐） ​

对于新项目：

shell
npm install @rrweb/record @rrweb/replay
js
import { record } from '@rrweb/record';
import { Replayer } from '@rrweb/replay';
import '@rrweb/replay/dist/style.css';

便捷的单包选项：

shell
npm install @rrweb/all
js
import { record, Replayer, pack, unpack } from '@rrweb/all';
import '@rrweb/all/dist/style.css';

旧版兼容包：

shell
npm install rrweb
js
import { record, Replayer } from 'rrweb';
import 'rrweb/dist/style.css';

2) 不使用打包器的浏览器环境（ESM） ​

html
<link
  rel="stylesheet"
  href="https://cdn.rrweb.com/replay/current/dist/style.css"
/>
<script type="module">
  import { record } from 'https://cdn.rrweb.com/record/current/dist/record.js';
  import { Replayer } from 'https://cdn.rrweb.com/replay/current/dist/replay.js';
</script>

使用 current 指向最新稳定版本，或固定到精确版本（例如 https://cdn.rrweb.com/record/2.0.0/dist/record.js 和 https://cdn.rrweb.com/replay/2.0.0/dist/replay.js），以获得不可变的 生产环境 URL。

3) 旧版直接 <script> 引入（UMD 回退方案） ​

仅用于兼容非模块化环境；现代浏览器 均支持上述 ESM 方式。

html
<link
  rel="stylesheet"
  href="https://cdn.rrweb.com/replay/current/dist/style.css"
/>
<script src="https://cdn.rrweb.com/record/current/dist/record.umd.cjs"></script>
<script src="https://cdn.rrweb.com/replay/current/dist/replay.umd.cjs"></script>

在 GitHub 上编辑 README

rrweb 发布说明 ​

2.1.1 ​

补丁变更 ​

  • 更新依赖 []：
    • rrweb-snapshot@2.1.1
    • rrdom@2.1.1
    • @rrweb/types@2.1.1
    • @rrweb/utils@2.1.1

2.1.0 ​

补丁变更 ​

  • #1864 7f0f75f 感谢 @eoghanmurray！ - 修复回放器的 getCurrentTime() 在实时模式（liveMode）下最后一个事件用尽后“卡住”的问题

  • 更新依赖 [b08a06f, 6fe4fed]：

    • rrweb-snapshot@2.1.0
    • @rrweb/types@2.1.0
    • rrdom@2.1.0
    • @rrweb/utils@2.1.0

2.0.1 ​

补丁变更 ​

  • #1854 5f52d63 感谢 @eoghanmurray！ - 修复当网页被第三方库 monkey patch 时 Webkit/Safari 中 MutationObserver 失效的问题

  • 更新依赖 [5f52d63]：

    • rrweb-snapshot@2.0.1
    • @rrweb/utils@2.0.1
    • rrdom@2.0.1
    • @rrweb/types@2.0.1

2.0.0 ​

重大变更 ​

  • #1497 2606a2a 感谢 @Juice10！ - 将插件从 rrweb 中拆分出来，移至它们各自的包：@rrweb/packer、@rrweb/rrweb-plugin-canvas-webrtc-record、@rrweb/rrweb-plugin-canvas-webrtc-replay、@rrweb/rrweb-plugin-sequential-id-record、@rrweb/rrweb-plugin-sequential-id-replay、@rrweb/rrweb-plugin-console-record、@rrweb/rrweb-plugin-console-replay。更多信息请查看各包的 README，或查看 https://github.com/rrweb-io/rrweb/pull/1033 了解这些变更。

  • #1497 2606a2a 感谢 @Juice10！ - 分发的文件使用了新的文件名、路径和扩展名。重要：如果你直接引用分发的文件或类型，可能需要更新路径/文件名。例如你从 rrweb/typings/... 或 rrdom/es 导入。但如果你使用 import rrweb from 'rrweb' 的方式导入，则不会受到此变更的影响。 如果你直接在 script 标签中引入 rrweb 文件，可能需要将该路径更新为 .umd.cjs 文件。所有 .js 文件现在使用 ES 模块，可在现代浏览器、node.js 以及支持 ES 模块的打包器中使用。所有 npm 包现在还同时提供 .cjs 和 .umd.cjs 文件。.umd.cjs 文件是将所有文件打包在一起的 CommonJS 模块，便于向浏览器环境分发单个文件（类似于之前的 .js 文件）。.cjs 文件是可在旧版 Node.js 环境中使用的 CommonJS 模块。类型在 package.json 中会有更完善的定义；如果你需要特定类型，它们可能从新的包中导出（例如 PlayerMachineState 和 SpeedMachineState 现在从 @rrweb/replay 导出）。请查看 package.json 的 main 和 exports 字段了解可用文件。

  • #1497 2606a2a 感谢 @Juice10！ - 从 rrweb 包中移除 rrweb-all.js、rrweb-record.js 和 rrweb-replay.js 文件。现在你可以改用 @rrweb/all、@rrweb/record 和 @rrweb/replay 包。更多信息请查看各包的 README，或查看 PR #1033 了解这些变更。

  • #1031 ad9bc3e 感谢 @Juice10！ - 将 rrweb 共享的事件和录制器类型移至新的 @rrweb/types 包。

  • #868 e4f680e 感谢 @Juice10！ - 移除 INode / node.__sn 的用法，改用 Mirror 作为事实来源。

  • #913 74f553a 感谢 @Yuyz0112！ - 将仅限浏览器的 rrdom 功能移至新的 rrdom 包。

次要变更 ​

  • #1129 979d2b1 感谢 @eoghanmurray！ - 点击事件现在包含 .pointerType 属性，用于区分 'pen'、'mouse' 和 'touch' 事件。没有新增 PenDown/PenUp 事件，但可以通过 MouseDown/MouseUp + pointerType=pen 检测它们

  • #1432 123a81e 感谢 @Juice10！ - 全面重构 video 和 audio 元素的播放。更加健壮，并修复了大量与暂停/播放/跳过/静音/playbackRate 等相关的 bug。

  • #1188 bc84246 感谢 @benjackwhite！ - feat：扩展 maskInputFn，将 HTMLElement 传递给决策函数

  • #1170 d2582e9 感谢 @mydea！ - feat：确保密码输入框在切换输入类型时仍保持脱敏状态

  • #1107 a225d8e 感谢 @mydea！ - feat：允许将 errorHandler 作为录制选项传入

  • #1503 335639a 感谢 @Juice10！ - 支持顶层 <dialog> 组件。修复 #1381。

  • #1310 7c0dc9d 感谢 @benjackwhite！ - 扩展 maskTextFn，将 HTMLElement 传递给决策函数

  • #1543 53b83bb 感谢 @JonasBa！ - 优化 isParentRemoved 检查

  • #1035 2a80949 感谢 @Juice10！ - 通过 recordCrossOriginIframes 新增对录制跨域 iframe 的支持。

  • #989 3809060 感谢 @YunFeng0817！ - 新增对可构造样式表 adoptedStyleSheets 的录制和回放支持，包括样式表变更、replace/replaceSync、shadow root、iframe、实时模式和虚拟 DOM 回放。

  • #936 b2d5689 感谢 @0jinxing！ - 新增对文本选择事件的录制和回放支持。

  • #953 5f59f91 感谢 @YunFeng0817！ - 新增 destroy() 方法，用于彻底移除回放器实例并发出销毁事件。

  • #976 a8478f1 感谢 @Juice10！ - 新增 canvas WebRTC 录制和回放插件，用于实时推流 canvas 内容。

  • #1000 ce6019d 感谢 @wfk007！ - 新增对媒体 playbackRate 变化的录制和回放支持。

  • #967 bac1d7b 感谢 @QxQstar！ - 新增 dataURLOptions，用于控制 canvas 快照图像的格式和质量。

  • #894 5ba933c 感谢 @dbseel！ - 新增 ignoreCSSAttributes，并在录制器的各个观察器中一致地应用 blockSelector 检查。

  • #859 e238462 感谢 @Juice10！ - 新增按配置的 FPS 录制 canvas 快照的支持。

  • #895 de755ae 感谢 @Juice10！ - 新增回放的快进虚拟 DOM 优化。

补丁变更 ​

2.0.0-alpha.20 ​

补丁变更 ​

  • #1763 6388fb5 感谢 @wfk007！ - fix：处理 wujie monkeypatch ownerDocument 的情况

  • 更新依赖 [6388fb5]：

    • @rrweb/utils@2.0.0-alpha.20
    • rrweb-snapshot@2.0.0-alpha.20
    • rrdom@2.0.0-alpha.20
    • @rrweb/types@2.0.0-alpha.20

2.0.0-alpha.19 ​

补丁变更 ​

2.0.0-alpha.18 ​

次要变更 ​

补丁变更 ​

  • #1535 04ee6ed 感谢 @eoghanmurray！ - 在 #1458 之后，对替换 :hover 的方式做小幅简化

  • #1437 5fbb904 感谢 @eoghanmurray！ - 边界情况：支持对（罕见地）包含多个文本节点的 <style> 元素的变更

  • #1593 5a78938 感谢 @daibhin！ - NodeType 枚举已从 rrweb-snapshot 移至 @rrweb/types 以下类型已从 rrweb-snapshot 移至 @rrweb/types：documentNode、documentTypeNode、legacyAttributes、textNode、cdataNode、commentNode、elementNode、serializedNode、serializedNodeWithId、serializedElementNodeWithId、serializedTextNodeWithId、IMirror、INode、mediaAttributes、attributes 和 DataURLOptions

  • 更新依赖 [8e55c45, 02cc62d, 04ee6ed, 5fbb904, 5a78938]：

    • rrdom@2.0.0-alpha.18
    • rrweb-snapshot@2.0.0-alpha.18
    • @rrweb/types@2.0.0-alpha.18
    • @rrweb/utils@2.0.0-alpha.18

2.0.0-alpha.17 ​

次要变更 ​

补丁变更 ​

  • #1417 40bbc25 感谢 @YunFeng0817！ - fix：修复 style 元素重复的 textContent 导致增量样式变更失效的问题

  • #1527 68076b7 感谢 @arredgroup！ - 为录制过程导出 takeFullSnapshot 函数

  • #1515 8059d96 感谢 @okejminja！ - 新增对已废弃的 addRule 与 removeRule 方法的支持

  • #1509 be6bf52 感谢 @Juice10！ - 反向 monkey patch 内置方法，以支持 LWC（以及 angular 等其他会 monkey patch 内置方法的框架）。

  • 更新依赖 [40bbc25, 335639a, 335639a, d350da8, be6bf52]：

    • rrweb-snapshot@2.0.0-alpha.17
    • rrdom@2.0.0-alpha.17
    • @rrweb/types@2.0.0-alpha.17
    • @rrweb/utils@2.0.0-alpha.17

2.0.0-alpha.16 ​

补丁变更 ​

  • #1386 a2c8a1a 感谢 @ababik！ - 修复可选的 maskInputFn 在创建全量快照时被意外忽略的问题

  • #1512 d08624c 感谢 @eoghanmurray！ - 优化：跳过叶子元素的脱敏检查

  • 更新依赖 [a2c8a1a, d08624c]：

    • rrweb-snapshot@2.0.0-alpha.16
    • rrdom@2.0.0-alpha.16
    • @rrweb/types@2.0.0-alpha.16

2.0.0-alpha.15 ​

重大变更 ​

  • #1497 2606a2a 感谢 @Juice10！ - 将插件从 rrweb 中拆分出来，移至它们各自的包：@rrweb/packer、@rrweb/rrweb-plugin-canvas-webrtc-record、@rrweb/rrweb-plugin-canvas-webrtc-replay、@rrweb/rrweb-plugin-sequential-id-record、@rrweb/rrweb-plugin-sequential-id-replay、@rrweb/rrweb-plugin-console-record、@rrweb/rrweb-plugin-console-replay。更多信息请查看各包的 README，或查看 https://github.com/rrweb-io/rrweb/pull/1033 了解这些变更。

  • #1497 2606a2a 感谢 @Juice10！ - 分发的文件使用了新的文件名、路径和扩展名。重要：如果你直接引用分发的文件或类型，可能需要更新路径/文件名。例如你从 rrweb/typings/... 或 rrdom/es 导入。但如果你使用 import rrweb from 'rrweb' 的方式导入，则不会受到此变更的影响。 如果你直接在 script 标签中引入 rrweb 文件，可能需要将该路径更新为 .umd.cjs 文件。所有 .js 文件现在使用 ES 模块，可在现代浏览器、node.js 以及支持 ES 模块的打包器中使用。所有 npm 包现在还同时提供 .cjs 和 .umd.cjs 文件。.umd.cjs 文件是将所有文件打包在一起的 CommonJS 模块，便于向浏览器环境分发单个文件（类似于之前的 .js 文件）。.cjs 文件是可在旧版 Node.js 环境中使用的 CommonJS 模块。类型在 package.json 中会有更完善的定义；如果你需要特定类型，它们可能从新的包中导出（例如 PlayerMachineState 和 SpeedMachineState 现在从 @rrweb/replay 导出）。请查看 package.json 的 main 和 exports 字段了解可用文件。

  • #1497 2606a2a 感谢 @Juice10！ - 从 rrweb 包中移除 rrweb-all.js、rrweb-record.js 和 rrweb-replay.js 文件。现在你可以改用 @rrweb/all、@rrweb/record 和 @rrweb/replay 包。更多信息请查看各包的 README，或查看 PR #1033 了解这些变更。

补丁变更 ​

  • #1033 7261c43 感谢 @Juice10！ - 直接从 rrweb 导出 ReplayPlugin。以前必须写成 import type { ReplayPlugin } from 'rrweb/dist/types';，现在可以写成 import type { ReplayPlugin } from 'rrweb';

  • #1468 4014305 感谢 @eoghanmurray！ - inlineImages：快照期间避免为内联同源图片添加事件监听器（异步监听器会修改快照，可能引发问题）

  • #1489 609b7fa 感谢 @JonasBa！ - 通过将 isParentRemoved 改为迭代过程来优化其性能

  • #1493 82f6fec 感谢 @eoghanmurray！ - 回放：替换 CSS 解析器正则表达式中的负向后行断言，因为它会在 Safari 16 中引发问题

  • #1353 5c27b76 感谢 @YunFeng0817！ - 修复：部分嵌套的跨域 iframe 无法被录制的问题

  • #1328 d38893f 感谢 @eoghanmurray！ - 重构后不再需要与 shadowDom 相关的、在后台持续运行的 raf 循环

  • #1295 d7cf8dd 感谢 @colingm！ - 对同源子 frame 提前返回

  • #760 e08706a 感谢 @eoghanmurray！ - 新增 slimDOM 选项以屏蔽 <title> 标签上的动画；当 slimDOM 使用 'all' 值时启用

  • 更新依赖 [4014305, 82f6fec, 2606a2a, f3cf092, e08706a]：

    • rrweb-snapshot@2.0.0-alpha.15
    • rrdom@2.0.0-alpha.15
    • @rrweb/types@2.0.0-alpha.15

2.0.0-alpha.14 ​

补丁变更 ​

2.0.0-alpha.13 ​

次要变更 ​

  • #1432 123a81e 感谢 @Juice10！ - 全面重构 video 和 audio 元素的播放。更加健壮，并修复了大量与暂停/播放/跳过/静音/playbackRate 等相关的 bug。

补丁变更 ​

2.0.0-alpha.12 ​

次要变更 ​

补丁变更 ​

2.0.0-alpha.11 ​

补丁变更 ​

2.0.0-alpha.10 ​

补丁变更 ​

  • #1269 7103625 感谢 @eoghanmurray！ - 不再包含刚添加节点上文本/属性变更中的冗余数据

  • #1268 d872d28 感谢 @eoghanmurray！ - 紧凑样式变更的修复与改进

    • 修复样式更新在简写属性上包含 'var()' 时的问题 #1246
    • 通过在字符串方式更短时回退到字符串方式，进一步确保样式变更保持紧凑

  • #1262 36da39d 感谢 @billyvg！ - feat：新增 ignoreSelector 选项

    与 ignoreClass 类似，但接受 CSS 选择器，因此你可以使用任意 CSS 选择器。

  • #1251 bbbfa22 感谢 @wfk007！ - fix：修复 iframe 出现后 Resize 和 MediaInteraction 事件重复生成的问题

  • #1254 d0fbe23 感谢 @mydea！ - 处理 event 为 null/undefined 的情况

  • #1273 a3de582 感谢 @Juice10！ - Canvas FPS 录制：在创建 canvas 时覆盖 preserveDrawingBuffer: true。 Canvas 回放：修复 canvas 元素闪烁的问题。 Canvas FPS 录制：修复录制时会清除 webgl(2) canvas 背景的 bug。

  • 更新依赖 [d872d28, c6600e7]：

    • @rrweb/types@2.0.0-alpha.10
    • rrweb-snapshot@2.0.0-alpha.10
    • rrdom@2.0.0-alpha.10

2.0.0-alpha.9 ​

补丁变更 ​

2.0.0-alpha.8 ​

次要变更 ​

补丁变更 ​

  • #1198 b5e30cf 感谢 @charliegracie！ - 在 Controller 的 goto 中（而非 handleProgressClick 中）重置 finished 标志，以便在直接调用 goto 时也能正确处理。

  • #1184 aa79db7 感谢 @mydea！ - fix：确保获取 input 的类型正常工作

  • 更新依赖 [979d2b1, bc84246, d0fdc0f]：

    • @rrweb/types@2.0.0-alpha.8
    • rrweb-snapshot@2.0.0-alpha.8
    • rrdom@2.0.0-alpha.8

2.0.0-alpha.7 ​

次要变更 ​

  • #1170 d2582e9 感谢 @mydea！ - feat：确保密码输入框在切换输入类型时仍保持脱敏状态

  • #1107 a225d8e 感谢 @mydea！ - feat：允许将 errorHandler 作为录制选项传入

补丁变更 ​

  • #1179 e0f862b 感谢 @wfk007！ - 修复：#1178 移除构建时与 worker_threads 相关的警告

  • #1186 267e990 感谢 @YunFeng0817！ - 修复：即使在不需要录制器的环境中也会创建 processed-node-manager 的问题

  • #1145 a82a3b4 感谢 @eoghanmurray！ - 对于移除节点的变更，考虑到可能是祖先节点（而不仅是父节点）刚被移除，减少误报警告的数量

  • #1191 1e6f71b 感谢 @Juice10！ - 仅在 flush 时应用 touch-active 样式

  • #1191 1e6f71b 感谢 @Juice10！ - 调用 replayer.pause(...) 时，随 mouse up 和 mouse down 事件触发鼠标移动与悬停。

  • #1163 4cb4d0e 感谢 @zhaobosky！ - 修复：部分网站重建不完整

    1. 部分网站中，emit 函数里的 addedSet 不为空，但 Array.from 转换的结果为空。
    2. 部分网站 polyfill 了 HTML 元素的 classList 方法，其实现可能抛错并导致快照失败。我添加了 try-catch 语句使代码更健壮。

  • 更新依赖 [d2582e9, e7f0c80]：

    • rrweb-snapshot@2.0.0-alpha.7
    • rrdom@2.0.0-alpha.7
    • @rrweb/types@2.0.0-alpha.7

2.0.0-alpha.6 ​

补丁变更 ​

2.0.0-alpha.5 ​

补丁变更 ​

1.0.0 ​

次要变更 ​

  • 支持录制同源的未沙箱化 iframe。
  • 支持录制 open 模式的 shadow DOM。
  • 实现插件 API。
  • 将 record.takeFullSnapshot 作为公共 API 导出。
  • 录制并回放拖拽事件。
  • 新增文本脱敏选项（#540）。

补丁变更 ​

  • 在 Angular patch 了 MutationObserver 时获取原始的 MutationObserver。
  • 修复 RangeError: Maximum call stack size exceeded（#479）。
  • 修复录制器中的链表实现。
  • 播放器暂停时不执行新添加的动作（#539）。
  • 修复鼠标位置不准确的问题（#522）。

重大变更 ​

  • 废弃 rrweb.mirror 的用法，请改用 record.mirror 和 replayer.getMirror()。
  • 废弃内置的 console 录制和回放选项。请参阅 console 指南中的插件 API。