rrweb 单仓库Monorepo包结构全解析record、replay、player 与周边工具链【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrwebrrwebrecord and replay the web以 npm 单仓库monorepo形式组织其全部代码packages/README.md 是该仓库所有发布包的官方索引是理解整个项目架构的起点。本文以该文档为主线逐一剖析 12 个包的职责、依赖关系与源码位置并给出面向不同使用场景的选型建议帮助你在阅读源码、参与贡献或进行二次开发时快速定位所需模块。包总览一张图看懂 rrweb 的模块划分根据 packages/README.mdrrweb 单仓库目前包含以下发布包包名职责定位核心源码入口rrweb同时包含录制与回放的原始包已废弃仅为向后兼容保留packages/rrweb/src/entries/record.ts、packages/rrweb/src/entries/replay.tsrrweb/record录制相关代码面向前端页面发布packages/record/src/index.tsrrweb/replay在 iframe 中重建并回放录制事件packages/replay/src/index.tsrrweb-player基于rrweb/replay的开箱即用回放 UIpackages/rrweb-player/src/Player.svelterrweb-snapshot将 DOM 快照为有状态、可序列化的数据结构是 FullSnapshot 事件的基础packages/rrweb-snapshot/src/snapshot.tsrrweb/types各包共享的 TypeScript 类型packages/types/src/index.tsrrweb/utils各包共享的工具函数packages/utils/src/index.tsrrdom虚拟 DOM 库用于回放时快速应用 DOM 变更packages/rrdom/src/diff.tsrrdom-nodejsrrdom的 Node.js 实现用于服务端处理 rrweb 数据packages/rrdom-nodejs/src/document-nodejs.tsrrvideo把 rrweb 会话录制转换为视频的 CLI 工具packages/rrvideo/src/cli.tsweb-extension录制与回放网页的浏览器扩展packages/web-extension/src/content/index.tsrrweb/packer网络传输前对事件逐条压缩packages/packer/src/pack.tsrrweb/all便捷聚合包包含 record、replay 与 packer不再包含任何插件packages/all/src/index.ts插件包如rrweb-plugin-console-record、rrweb-plugin-network-record等不在本索引内另见 插件 API 文档。核心二包rrweb/record与rrweb/replay的分工在大多数生产部署中录制端与回放端位于不同的页面或应用因此项目将录制与回放拆分为两个独立包rrweb/record包含 rrweb 全部录制相关代码面向前端应用/网页发布。其 README 明确说明当前它本质上还是主rrweb包中record函数的包装器未来所有录制代码会逐步迁移至此见 packages/record/README.md。rrweb/replay包含回放已录制事件所需的全部代码但只做基础回放UI 与控制栏交给使用者自行实现见 packages/replay/README.md。通过 npm 安装并组合使用npm install rrweb/record rrweb/replayimport { record } from rrweb/record; import { Replayer } from rrweb/replay; import rrweb/replay/dist/style.css; // 录制端采集事件并交由 emit 回调上传 record({ emit(event) { // send event to server }, });关于record的全部配置项record options可参考 guide.md 中的 Getting Started 章节。浏览器端无打包器ESM加载方式rrweb/record与rrweb/replay均提供 CDN 直引的 ESM 产物适合无构建链路的场景link relstylesheet hrefhttps://cdn.rrweb.com/replay/current/dist/style.css / script typemodule 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。两包还额外提供 UMD 兼容产物record.umd.cjs/replay.umd.cjs对应的全局变量分别为rrwebRecord与rrwebReplay仅用于不支持模块的老环境。被拆分的原包rrweb为什么被废弃原rrweb包同时包含 record 与 replay 两份逻辑现已标记为Deprecated仅为了向后兼容而保留。其 README 明确指出New projects should depend onrrweb/recordandrrweb/replaydirectly, or userrweb/allfor a single convenience import.从源码结构看该包的 packages/rrweb/src/record 与 packages/rrweb/src/replay 目录仍然是 record 与 replay 两类 TypeScript 代码的实际所在packages/rrweb/README.md 的 Dev Note 也说明这一点这些代码最终会被重构迁移到各自独立包中。也就是说当前rrweb/record与rrweb/replay的入口是对旧包内实现的再导出。对于仍在使用旧包的项目其安装与使用方式为npm install rrwebimport { record, Replayer } from rrweb; import rrweb/dist/style.css;开箱即用的回放 UIrrweb-player如果不想自己实现回放控制栏可以直接使用rrweb-player——它基于rrweb/replay用 Svelte UI 框架封装出了播放/暂停控制与时间线官方云控制台app.rrweb.com使用的正是这一回放器。它与new Replayer()的关键区别在于后者只负责在 iframe 内渲染重建事件流前者在此基础上提供完整 UI见 packages/rrweb-player/README.md。npm install rrweb-playerimport rrwebPlayer from rrweb-player; import rrweb-player/dist/style.css; new rrwebPlayer({ target: document.body, // customizable root element props: { events, }, });其组件级配置项如下表key默认值说明events[]用于回放的事件数组width1024回放器宽度height576回放器高度maxScale1回放器最大缩放比例1 100%设为 0 表示不限autoPlaytrue是否自动播放speed1默认播放速度speedOption[1, 2, 4, 8]UI 中可选的速度档位showControllertrue是否显示控制栏 UItags{}以键值对自定义 custom events 的样式inactiveColor#D4D4D4进度条中非活跃时段的指示颜色合法 CSS 颜色字符串...-其余参数全部透传给底层Replayer的配置此外rrwebPlayer 组件实例暴露了addEventListener、addEvent、getMetaData()返回startTime/endTime/totalTime、getReplayer()、getMirror()等方法方便在外部控制回放流程。序列化基础rrweb-snapshotrrweb-snapshot是所有事件数据格式的基石它将 DOM 快照为有状态、可序列化的数据结构并提供反向重建 DOM 的能力是录制中 FullSnapshot 事件的基础见 packages/rrweb-snapshot/README.md。其公开 API 包括snapshot遍历 DOM 并返回可表示当前 DOM视图的序列化结构。快照过程中会做五件事把部分 DOM 状态内联进 HTML 属性如HTMLInputElement的 value将script标签转为noscript避免脚本被执行尝试内联样式表保证本地样式可用将 href、src、CSS 中的相对路径改为绝对路径为每个 Node 分配 id并在快照完成后返回 id 节点映射表。rebuild根据快照构建 DOM。在浏览器环境中rebuild()是底层 API除非传入UNSAFE_allowUnprotectedRebuild: true否则要求使用rebuildIntoSandboxedIframe()创建的 document——不可信任的回放数据绝不能直接重建到顶层 document 或调用方自建的 iframe document 中。重建过程中会为 Element 添加data-rrid属性、创建额外 DOM 节点放置内联 CSS 与部分状态、为含额外子 DOM 的节点添加data-extra-child-index属性。rebuildIntoSandboxedIframe浏览器环境推荐使用的安全入口需要显式传入root元素const { iframe, node } rebuildIntoSandboxedIframe(snapshot, { root: document.body, cache, mirror, });需要自行管理 iframe 时可先用createSandboxedIframe()创建再调用rebuild()。serializeNodeWithId将单个节点序列化为带 id 的快照格式。buildNodeWithSN从序列化节点构建 DOM并将序列化信息存入mirror.getMeta(node)。这些安全约定对应仓库中的 sandbox 设计文档 与 ADRrequire sandboxed browser rebuilds。共享基础设施rrweb/types与rrweb/utilsrrweb/types提供各包共享的 TypeScript 类型。rrweb 大量依赖 TS 类型来保证正确性并定义包间数据 API主事件类型Event的介绍见 事件文档。rrweb/utils提供各包共享的工具函数具体实现见 packages/utils/src/index.ts。这两个包都只承担基础能力不依赖业务逻辑是其他包的公共依赖。回放性能引擎rrdom与rrdom-nodejsrrdom一个独立的虚拟 DOM 库用于回放时快速应用 DOM 变更mutation。rrweb 借助它在拖动时间轴 seek 时优化回放性能——不是逐条重放增量而是对虚拟 DOM 树打补丁patch到真实 DOM见 packages/rrdom/README.md。其核心 diff 逻辑在 packages/rrdom/src/diff.ts。rrdom-nodejsrrdom的 Node.js 实现用于服务端处理 rrweb 数据——可以在 Node 环境中回放并检查录制的用户交互适合服务端渲染、数据校验或测试场景见 packages/rrdom-nodejs/README.md。离线与周边工具rrvideo与web-extensionrrvideo把 rrweb 录制的会话JSON 格式事件文件转换为视频的 CLI 工具安装与使用方式详见 packages/rrvideo/README.mdnpm i -g rrvideo rrvideo --input PATH_TO_YOUR_RRWEB_EVENTS_FILE命令会在当前目录输出rrvideo-output.webm文件。另提供 中文文档 与示例配置 packages/rrvideo/rrvideo.config.example.json。web-extension提供录制与回放网页的浏览器扩展支持 Chrome 与 Firefox 构建packages/web-extension/README.md# build for chrome yarn build:chrome # build for firefox yarn build:firefox压缩与聚合rrweb/packer与rrweb/allrrweb/packer在前端完成网络传输前的逐事件压缩基于fflate的 zlib 压缩每个 rrweb 事件在产出时被单独压缩。录制端需要引入编码器约增加 17KBminifiedgzip 后更小包体回放端的解压由独立的rrweb/packer/unpack入口处理见 packages/packer/README.md。工作原理详见 存储优化 recipe。rrweb/all便捷聚合包包含rrweb、rrweb/record、rrweb/replay、rrweb/packer适合 demo、工具类或希望单一依赖导入的场景它与旧rrweb包的作用类似但不再包含任何插件见 packages/all/README.md。npm install rrweb/allimport { record, Replayer, pack, unpack } from rrweb/all; import rrweb/all/dist/style.css;选型指南不同场景下如何选择包综合 packages/README.md、packages/rrweb/README.md 与 packages/all/README.md 的说明选择逻辑可以归纳为使用场景推荐包组合大多数新应用录制与回放分别部署rrweb/recordrrweb/replay需要开箱即用的回放控制 UIrrweb/replayrrweb-player单一依赖同时拿到 record、replay 与 packerrrweb/all兼容旧项目rrweb已废弃仅向后兼容服务端处理/回放 rrweb 数据rrdom-nodejs把录制转成视频文件rrvideo浏览器扩展形态的录制/回放web-extension传输前压缩事件体积rrweb/packer如何继续深入录制与回放的完整使用教程与全部配置项阅读 guide.md含 Getting Started、record options 与 replay options。事件数据结构详解阅读 事件文档。录制原理observer 架构阅读 observer.md。回放原理阅读 replay.md。快照与序列化细节阅读 serialization.md。插件体系阅读 插件 API 文档 与 插件 recipe。参与贡献参考 CONTRIBUTING.md注意当前 record 与 replay 的 PR 仍主要在rrweb包内提交见 packages/rrweb/README.md 的 Dev Note。【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrweb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 rrweb 单仓库（Monorepo）包结构全解析：record、replay、player 与周边工具链
rrweb 单仓库Monorepo包结构全解析record、replay、player 与周边工具链【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrwebrrwebrecord and replay the web以 npm 单仓库monorepo形式组织其全部代码packages/README.md 是该仓库所有发布包的官方索引是理解整个项目架构的起点。本文以该文档为主线逐一剖析 12 个包的职责、依赖关系与源码位置并给出面向不同使用场景的选型建议帮助你在阅读源码、参与贡献或进行二次开发时快速定位所需模块。包总览一张图看懂 rrweb 的模块划分根据 packages/README.mdrrweb 单仓库目前包含以下发布包包名职责定位核心源码入口rrweb同时包含录制与回放的原始包已废弃仅为向后兼容保留packages/rrweb/src/entries/record.ts、packages/rrweb/src/entries/replay.tsrrweb/record录制相关代码面向前端页面发布packages/record/src/index.tsrrweb/replay在 iframe 中重建并回放录制事件packages/replay/src/index.tsrrweb-player基于rrweb/replay的开箱即用回放 UIpackages/rrweb-player/src/Player.svelterrweb-snapshot将 DOM 快照为有状态、可序列化的数据结构是 FullSnapshot 事件的基础packages/rrweb-snapshot/src/snapshot.tsrrweb/types各包共享的 TypeScript 类型packages/types/src/index.tsrrweb/utils各包共享的工具函数packages/utils/src/index.tsrrdom虚拟 DOM 库用于回放时快速应用 DOM 变更packages/rrdom/src/diff.tsrrdom-nodejsrrdom的 Node.js 实现用于服务端处理 rrweb 数据packages/rrdom-nodejs/src/document-nodejs.tsrrvideo把 rrweb 会话录制转换为视频的 CLI 工具packages/rrvideo/src/cli.tsweb-extension录制与回放网页的浏览器扩展packages/web-extension/src/content/index.tsrrweb/packer网络传输前对事件逐条压缩packages/packer/src/pack.tsrrweb/all便捷聚合包包含 record、replay 与 packer不再包含任何插件packages/all/src/index.ts插件包如rrweb-plugin-console-record、rrweb-plugin-network-record等不在本索引内另见 插件 API 文档。核心二包rrweb/record与rrweb/replay的分工在大多数生产部署中录制端与回放端位于不同的页面或应用因此项目将录制与回放拆分为两个独立包rrweb/record包含 rrweb 全部录制相关代码面向前端应用/网页发布。其 README 明确说明当前它本质上还是主rrweb包中record函数的包装器未来所有录制代码会逐步迁移至此见 packages/record/README.md。rrweb/replay包含回放已录制事件所需的全部代码但只做基础回放UI 与控制栏交给使用者自行实现见 packages/replay/README.md。通过 npm 安装并组合使用npm install rrweb/record rrweb/replayimport { record } from rrweb/record; import { Replayer } from rrweb/replay; import rrweb/replay/dist/style.css; // 录制端采集事件并交由 emit 回调上传 record({ emit(event) { // send event to server }, });关于record的全部配置项record options可参考 guide.md 中的 Getting Started 章节。浏览器端无打包器ESM加载方式rrweb/record与rrweb/replay均提供 CDN 直引的 ESM 产物适合无构建链路的场景link relstylesheet hrefhttps://cdn.rrweb.com/replay/current/dist/style.css / script typemodule 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。两包还额外提供 UMD 兼容产物record.umd.cjs/replay.umd.cjs对应的全局变量分别为rrwebRecord与rrwebReplay仅用于不支持模块的老环境。被拆分的原包rrweb为什么被废弃原rrweb包同时包含 record 与 replay 两份逻辑现已标记为Deprecated仅为了向后兼容而保留。其 README 明确指出New projects should depend onrrweb/recordandrrweb/replaydirectly, or userrweb/allfor a single convenience import.从源码结构看该包的 packages/rrweb/src/record 与 packages/rrweb/src/replay 目录仍然是 record 与 replay 两类 TypeScript 代码的实际所在packages/rrweb/README.md 的 Dev Note 也说明这一点这些代码最终会被重构迁移到各自独立包中。也就是说当前rrweb/record与rrweb/replay的入口是对旧包内实现的再导出。对于仍在使用旧包的项目其安装与使用方式为npm install rrwebimport { record, Replayer } from rrweb; import rrweb/dist/style.css;开箱即用的回放 UIrrweb-player如果不想自己实现回放控制栏可以直接使用rrweb-player——它基于rrweb/replay用 Svelte UI 框架封装出了播放/暂停控制与时间线官方云控制台app.rrweb.com使用的正是这一回放器。它与new Replayer()的关键区别在于后者只负责在 iframe 内渲染重建事件流前者在此基础上提供完整 UI见 packages/rrweb-player/README.md。npm install rrweb-playerimport rrwebPlayer from rrweb-player; import rrweb-player/dist/style.css; new rrwebPlayer({ target: document.body, // customizable root element props: { events, }, });其组件级配置项如下表key默认值说明events[]用于回放的事件数组width1024回放器宽度height576回放器高度maxScale1回放器最大缩放比例1 100%设为 0 表示不限autoPlaytrue是否自动播放speed1默认播放速度speedOption[1, 2, 4, 8]UI 中可选的速度档位showControllertrue是否显示控制栏 UItags{}以键值对自定义 custom events 的样式inactiveColor#D4D4D4进度条中非活跃时段的指示颜色合法 CSS 颜色字符串...-其余参数全部透传给底层Replayer的配置此外rrwebPlayer 组件实例暴露了addEventListener、addEvent、getMetaData()返回startTime/endTime/totalTime、getReplayer()、getMirror()等方法方便在外部控制回放流程。序列化基础rrweb-snapshotrrweb-snapshot是所有事件数据格式的基石它将 DOM 快照为有状态、可序列化的数据结构并提供反向重建 DOM 的能力是录制中 FullSnapshot 事件的基础见 packages/rrweb-snapshot/README.md。其公开 API 包括snapshot遍历 DOM 并返回可表示当前 DOM视图的序列化结构。快照过程中会做五件事把部分 DOM 状态内联进 HTML 属性如HTMLInputElement的 value将script标签转为noscript避免脚本被执行尝试内联样式表保证本地样式可用将 href、src、CSS 中的相对路径改为绝对路径为每个 Node 分配 id并在快照完成后返回 id 节点映射表。rebuild根据快照构建 DOM。在浏览器环境中rebuild()是底层 API除非传入UNSAFE_allowUnprotectedRebuild: true否则要求使用rebuildIntoSandboxedIframe()创建的 document——不可信任的回放数据绝不能直接重建到顶层 document 或调用方自建的 iframe document 中。重建过程中会为 Element 添加data-rrid属性、创建额外 DOM 节点放置内联 CSS 与部分状态、为含额外子 DOM 的节点添加data-extra-child-index属性。rebuildIntoSandboxedIframe浏览器环境推荐使用的安全入口需要显式传入root元素const { iframe, node } rebuildIntoSandboxedIframe(snapshot, { root: document.body, cache, mirror, });需要自行管理 iframe 时可先用createSandboxedIframe()创建再调用rebuild()。serializeNodeWithId将单个节点序列化为带 id 的快照格式。buildNodeWithSN从序列化节点构建 DOM并将序列化信息存入mirror.getMeta(node)。这些安全约定对应仓库中的 sandbox 设计文档 与 ADRrequire sandboxed browser rebuilds。共享基础设施rrweb/types与rrweb/utilsrrweb/types提供各包共享的 TypeScript 类型。rrweb 大量依赖 TS 类型来保证正确性并定义包间数据 API主事件类型Event的介绍见 事件文档。rrweb/utils提供各包共享的工具函数具体实现见 packages/utils/src/index.ts。这两个包都只承担基础能力不依赖业务逻辑是其他包的公共依赖。回放性能引擎rrdom与rrdom-nodejsrrdom一个独立的虚拟 DOM 库用于回放时快速应用 DOM 变更mutation。rrweb 借助它在拖动时间轴 seek 时优化回放性能——不是逐条重放增量而是对虚拟 DOM 树打补丁patch到真实 DOM见 packages/rrdom/README.md。其核心 diff 逻辑在 packages/rrdom/src/diff.ts。rrdom-nodejsrrdom的 Node.js 实现用于服务端处理 rrweb 数据——可以在 Node 环境中回放并检查录制的用户交互适合服务端渲染、数据校验或测试场景见 packages/rrdom-nodejs/README.md。离线与周边工具rrvideo与web-extensionrrvideo把 rrweb 录制的会话JSON 格式事件文件转换为视频的 CLI 工具安装与使用方式详见 packages/rrvideo/README.mdnpm i -g rrvideo rrvideo --input PATH_TO_YOUR_RRWEB_EVENTS_FILE命令会在当前目录输出rrvideo-output.webm文件。另提供 中文文档 与示例配置 packages/rrvideo/rrvideo.config.example.json。web-extension提供录制与回放网页的浏览器扩展支持 Chrome 与 Firefox 构建packages/web-extension/README.md# build for chrome yarn build:chrome # build for firefox yarn build:firefox压缩与聚合rrweb/packer与rrweb/allrrweb/packer在前端完成网络传输前的逐事件压缩基于fflate的 zlib 压缩每个 rrweb 事件在产出时被单独压缩。录制端需要引入编码器约增加 17KBminifiedgzip 后更小包体回放端的解压由独立的rrweb/packer/unpack入口处理见 packages/packer/README.md。工作原理详见 存储优化 recipe。rrweb/all便捷聚合包包含rrweb、rrweb/record、rrweb/replay、rrweb/packer适合 demo、工具类或希望单一依赖导入的场景它与旧rrweb包的作用类似但不再包含任何插件见 packages/all/README.md。npm install rrweb/allimport { record, Replayer, pack, unpack } from rrweb/all; import rrweb/all/dist/style.css;选型指南不同场景下如何选择包综合 packages/README.md、packages/rrweb/README.md 与 packages/all/README.md 的说明选择逻辑可以归纳为使用场景推荐包组合大多数新应用录制与回放分别部署rrweb/recordrrweb/replay需要开箱即用的回放控制 UIrrweb/replayrrweb-player单一依赖同时拿到 record、replay 与 packerrrweb/all兼容旧项目rrweb已废弃仅向后兼容服务端处理/回放 rrweb 数据rrdom-nodejs把录制转成视频文件rrvideo浏览器扩展形态的录制/回放web-extension传输前压缩事件体积rrweb/packer如何继续深入录制与回放的完整使用教程与全部配置项阅读 guide.md含 Getting Started、record options 与 replay options。事件数据结构详解阅读 事件文档。录制原理observer 架构阅读 observer.md。回放原理阅读 replay.md。快照与序列化细节阅读 serialization.md。插件体系阅读 插件 API 文档 与 插件 recipe。参与贡献参考 CONTRIBUTING.md注意当前 record 与 replay 的 PR 仍主要在rrweb包内提交见 packages/rrweb/README.md 的 Dev Note。【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrweb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考