简介rrweb 录制生成的 JSON 原始数据在回放时需依赖页面上的图片、CSS 等静态资源随着项目持续迭代这些资源的 hash 值往往已变更甚至被删除导致回放画面异常。这份面向 JavaScript 前端的工具项目正是为此而生将 rrweb 原始数据直接转换为视频实现永久保存与离线查看适合使用 rrweb 做用户行为录屏回放、需要长期留档的开发者。资源包共 11 个文件以 6 个 JS 文件为主体覆盖项目入口、服务端、页面脚本与打包配置等环节另含 JSON 配置、HTML 回放页面、README 说明文档及 .gitignore 忽略规则结构清晰明了。整个压缩包仅 47KB轻量精简只需安装并配置好 FFmpeg 环境即可通过命令行将 JSON 转换生成 mp4 视频。目前已有 2574 人学习浏览随包提供完整源码、构建配置与测试示例可快速理解转换流程并接入自身项目为回放数据永久留存提供可靠方案。1. 从事件流到视频文件为什么回放需要被固化成 mp4做过用户行为回放的都知道rrweb 把页面操作录成 JSON 事件流体积比录屏小一个量级分析时却要开着浏览器一段段回放没法直接交付、没法归档到对象存储。rrweb-to-video 这类工具把 rrweb 原始数据按时间顺序渲染到 canvas再用 MediaRecorder 录制成 mp4等于把「需要环境的回放」固化成一个普通视频文件。它适合三类人做客服质检要留证据的、做用户行为分析要批量产出的、以及需要把录制数据长期归档但不想依赖播放器的。核心一句话录屏做的是屏幕rrweb 做的是 DOMrrweb-to-video 做的是把 DOM 恢复成画面再录下来落地的关键是 JavaScript 侧对事件流时序和编码参数的控制。下面把链路拆开参数和坑都按可复现来写。2. rrweb 数据结构和转换链路事件流是怎么一步步变成 canvas 的对只拿 rrweb 录过数据、没仔细看过事件流的人来说第一步是把数据结构吃透。rrweb 输出的是一个数组每个元素是一个 eventevent 里有 type、timestamp、data 三个固定字段其余都是 data 下的子字段。type 为 0 的是 Meta 事件记录当时页面的宽高和 hreftype 为 2 是 FullSnapshot存的是整个 DOM 的序列化快照type 为 3 是 IncrementalSnapshot负责后续所有增量变化比如输入、鼠标移动、DOM 修改和样式变化。回放时就是先拿 Meta 和 FullSnapshot 建立初始页面再拿着按时间戳排序的增量事件逐个应用最后才能谈得上把画面输出成视频。2.1 快照、增量与时间戳rrweb events 的三段式结构把一段 rrweb 数据打印出来看常见结构是这样的[ { type: 0, timestamp: 1690000000000, data: { href: https://example.com/checkout, width: 1440, height: 900 } }, { type: 2, timestamp: 1690000000100, data: { node: { tagName: html, childNodes: [ { tagName: body, childNodes: [] } ] } } }, { type: 3, timestamp: 1690000000200, data: { source: 2, texts: [{ id: 12, value: 已选 2 件商品 }] } } ]这段 JSON 说明三件事第一个事件建立画布尺寸和页面地址第二个事件把 DOM 全量画出来第三个事件是增量只改 id 为 12 的节点的文本。回放引擎拿到这段数据后实际是在内存 DOM 里渲染不是直接操作视频帧所以效率高、体积小但代价是回放必须依赖 JavaScript 运行环境。参数说明要留意几点。type 0 的 data.width 和 data.height 决定了最终视频的宽高比例转码时如果强制把输出尺寸设成和这里不一致要么留边、要么拉伸。type 2 的 data.node 是序列化后的 DOM 树自闭合节点、input 的 checked 状态、canvas 的快照内容都会以特殊字段保存。type 3 的 data.source 细分了增量类型source 为 0 是鼠标交互为 1 是滚动为 2 是文本内容变化。每个事件的 timestamp 是绝对时间戳回放进度算的是相邻事件的时间戳差值。需要特别留意的rrweb 的快照不是简单 innerHTML。它会给每个节点分配 id在增量事件里用 id 引用节点跨事件序列化是稳定的。转视频时如果发现某个输入框内容没变化先检查增量事件里 texts 字段的 id 在 FullSnapshot 里是否存在。id 对不上说明录制端和回放端的 rrweb 版本不一致这是最容易被忽略的黑匣子。2.2 转换链路里最关键的一跳canvas 流与 MediaRecorderrrweb 自己只做录制和回放不做视频输出。rrweb-to-video 的切入点在回放的渲染层回放时不是直接在页面 DOM 里铺开而是把回放窗口渲染到一个 canvas 上再用 canvas.captureStream(fps) 拿到实时视频流最后交给 MediaRecorder 编码。这一步的代码形态就是标准事件流const canvas document.getElementById(replay); const context canvas.getContext(2d); const stream canvas.captureStream(30); const recorder new MediaRecorder(stream, { mimeType: video/webm;codecsvp9, videoBitsPerSecond: 3_000_000, }); recorder.ondataavailable (e) chunks.push(e.data); recorder.start(); // 这里由回放引擎持续驱动 canvas 重绘 recorder.stop();代码逻辑captureStream 接受一个帧率参数告诉浏览器从 canvas 里取画面的频率MediaRecorder 接到这个 MediaStream 后开始编码。回放引擎每处理一个新事件都重新绘制 canvas而不是逐帧用 requestAnimationFrame 硬刷这样能省掉大量无意义的重复绘制。常见的错误理解是把 MediaRecorder 当成瞬时录屏器。实际上 captureStream 的帧率上限由 canvas 的重绘频率决定如果事件流里两秒没有变化canvas 没有新帧产出某些浏览器会把这 2 秒录成黑帧或者直接跳过这会造成后面黑屏问题。处理方式是给 canvas 绘制加一个固定频率的循环在无事件时也重绘当前状态保证视频流不断帧。为什么不直接用浏览器原生录屏或现成的屏幕录制库两个原因。一是 rrweb 事件的回放发生在内存 DOM 里不产生真实屏幕画面录屏工具只能录到页面 URL 和 loading 状态。二是在无头浏览器里Chrome 的 tab 捕获经常拿不到 canvas 的加速合成层转出来白屏概率极高。canvas.captureStream 从 JavaScript 层面直接拿流绕开了系统录屏权限也绕开了 GPU 合成层的坑这是 rrweb-to-video 最值得学习的一条选型思路。另一个和 headless 环境强相关的点是时间驱动。rrweb 回放有一个基准时间所有增量事件都相对基准推进。普通回放里页面用 requestAnimationFrame 驱动每帧推进一段时间转到无头浏览器后rAF 仍然存在但页面不可见时浏览器会把帧率降到很低导致录制出的视频时间被拉长。常见做法是在注入脚本里强制用一个固定帧率的绘制时钟替代 rAF并且把页面置于可见状态。这些细节在 rrweb 的回放 demo 里表现不出来只有跑到转换视频时才会暴露。3. 从 npm 包到 mp4rrweb-to-video 完整复现一次转换要在自己环境里把 rrweb 原始数据转成视频直接把整个仓库 clone 下来当黑匣子跑是最容易翻车的路径。我更建议按它的核心链路自己搭一次Node 脚本拉起一个无头浏览器注入回放渲染逻辑等事件回放完停止录制输出文件。这样每一步都有日志可看出问题能定位到具体环节而不是看着一个 node 进程报一个含糊的退出码。3.1 环境准备Node、Puppeteer 与浏览器内核版本搭配依赖先装三个puppeteer-core、rrweb 的回放包、以及转码封装包。安装命令如下mkdir rrweb-to-video-demo cd rrweb-to-video-demo npm init -y npm i puppeteer-core rrweb rrweb-to-video如果你在 CI 或服务器上跑建议直接用 puppeteer 而不是 puppeteer-core。puppeteer 会自动下载 Chromium体积大约 150 MB省去手动装 Chrome 的麻烦puppeteer-core 默认不下载浏览器适合本机已有 Chrome 的环境。注意 Firefox 的 MediaRecorder 对 canvas.captureStream 支持不完整导出环节请固定在 Chromium 系浏览器。这里有一个必须提前处理的点无头浏览器的自动播放策略。MediaRecorder 的启动在部分 Chromium 版本里会被当成需要用户手势的媒体操作导致 recorder.start() 不执行。常见做法是在启动浏览器时加两个参数--autoplay-policyno-user-gesture-required 和 --use-fake-ui-for-media-stream。前者放行自动播放后者跳过麦克风和摄像头授权弹窗。如果你在本地跑没问题、上服务器就空白优先检查这两个参数。生产环境还需要确认 Chromium 的 GPU 加速是否开启。默认 new headless 模式下canvas 的 2D 上下文可能走 SwiftShader 软件渲染转出来的视频会明显掉帧。这时候关掉 headless 或者显式传 --use-glswiftshader等视频转完再切回来。软件渲染不影响视频内容正确性只影响性能和帧率稳定性批量转换时可以接受。3.2 最小化转码脚本把一份 events 换成 mp4写一个 Node 脚本 convert.js接收输入文件路径和输出路径两个参数const fs require(fs); const { toVideo } require(rrweb-to-video); const [, , inputPath, outputPath] process.argv; (async () { const events JSON.parse(fs.readFileSync(inputPath || ./events.json, utf8)); await toVideo({ events, output: outputPath || ./output/result.mp4, width: 1440, height: 900, fps: 30, mimeType: video/webm;codecsh264, inlineAssets: true, compressIdle: { threshold: 5000, ratio: 20 }, }); console.log(converted:, outputPath || ./output/result.mp4); })();逻辑说明toVideo 是这类仓库封装的转换入口核心行为是按 events 重建页面、设置画布尺寸、渲染回放、启动录制。events 直接传原始 JSON 数组output 是产物路径width 和 height 强制覆盖画布尺寸fps 决定 captureStream 取帧频率mimeType 优先请求 h264 编码inlineAssets 把 CSS、图片内联成 data URL减少网络加载导致的样式闪烁。参数说明有几个坑点。width 和 height 如果和事件里的 Meta 不一致产物会被拉伸所以建议从 events 的第一个 type 为 0 的事件里读取而不是硬编码。mimeType 请求 h264 后浏览器可能不支持而静默回退到 vp9不报错但文件后缀是 mp4、实际编码是 vp9交付前必须用 ffprobe 验证。compressIdle 是空闲压缩配置threshold 单位是毫秒ratio 表示把超过 threshold 的空闲段压缩为原来的 1/20这个参数对长会话录制尤其重要。跑一下看看效果node convert.js ./events.json ./output/result.mp4跑完用 ffprobe 验证实际编码ffprobe -v error -show_entries streamcodec_name,width,height,r_frame_rate -of json ./output/result.mp4这条命令能看到三个关键信息codec_name 是实际视频编码width 和 height 是实际分辨率r_frame_rate 是实际帧率。如果 codec_name 不是 h264 而是 vp9说明 mimeType 回退了后续要决定是接受 webm 产物还是用 ffmpeg 再转一次。r_frame_rate 如果显示 30/1 而实际播放卡顿再查 canvas 的重绘日志。3.3 批量转换与产物校验从 demo 走向生产真实场景是几十甚至几百个 JSON 文件要一起转。写一个 bash 循环for f in data/events_*.json; do name$(basename $f .json) node convert.js $f output/${name}.mp4 || echo FAIL ${name} batch.log ffprobe -v error -select_streams v:0 -show_entries streamcodec_name -of csvp0 output/${name}.mp4 done循环逻辑很直白遍历 data 目录下所有 events 开头的 JSON 文件逐个转换转换失败记入 batch.log成功则用 ffprobe 打印视频编码。批量处理时要把日志落盘不要只打到终端几百个文件跑下来终端缓冲会被撑爆而且失败记录容易丢。这里容易踩一个性能坑循环里每次执行 node convert.js 都会重新拉起一个浏览器实例对几百个文件来说时间会翻很多倍。建议在 Node 脚本里循环处理同一个浏览器实例只在 pages 间切换或者用并发队列控制同时最多跑 4 个转换任务。无头浏览器的内存占用通常在 300 MB 左右并发开多了会直接 OOM不是 CPU 不够的问题。另一个坑是失败重试。rrweb 数据偶发有损坏的 JSONJSON.parse 直接抛异常脚本退出。批量转换前先做一次格式校验常见的做法是跑一个 node -e 脚本把所有文件先 JSON.parse 一遍过滤出失败名单再进入正式转换流程避免转了一半才发现第 37 个文件是坏的。这一步五分钟能省下后面半小时的返工。4. 录制参数边界帧率、编码和时长对齐该设多少转换产物的质量不是越高越好而是要和事件频率、存储成本、后续处理折中。视频参数设得不对最常见的结果是文件巨大但画面内容稀疏或者文件很小但关键操作糊成一片。参数选型要围绕「场景是客服质检还是用户行为分析」来定而不是照搬默认值。4.1 影响产物质量的关键参数速查参数推荐值边界与影响width / height与 Meta 事件一致不一致会拉伸或留边语音回放场景建议锁 16:9fps30低于 15 动画卡顿高于 60 对 canvas 重绘压力大videoBitsPerSecond3-6 Mbps纯文本界面 2M 够动态图表需要 6MmimeTypevideo/webm;codecsh264 优先Chromium 对 h264 支持不稳定需要 ffprobe 回验compressIdle.threshold3000-5000ms低于 2s 会误压缩打字停顿高于 10s 压缩效果差waitUntilnetworkidle0网络慢时 DOM 未就绪快照会变形参数说明width 和 height 不建议按播放平台尺寸硬设而应该读取 events 第一个 meta 事件的 data.width 和 data.height。fps 设 30 是大多数视频平台的基线客服场景不需要 60fps因为鼠标轨迹和界面变化在 30fps 下已经完整数据可视化动画多的场景再上 60。videoBitsPerSecond 是码率上限不是目标码率纯文本界面设 2Mbps 足够页面里如果有地图或实时图表至少 6Mbps否则拖动时会出现马赛克。mimeType 值得单独说Chromium 系浏览器对 video/webm;codecsh264 的支持不稳定很多版本会直接回退到 vp9不报错、不警告。如果你交付对象要求 mp4脚本里要做两层准备第一层请求 h264第二层用 ffprobe 检测实际编码不对就自动走 ffmpeg 转换。不要在代码里写死 mp4 就以为产物是 h264这事我翻过车。4.2 时长对齐与空闲压缩策略时长对齐是 rrweb-to-video 里最影响交付质量的指标。rrweb 的 events 里时间戳是绝对毫秒值但有些录制端会把一段空闲期的最后一条事件时间戳一直往后推造成事件流时间轴和实际操作时间严重偏离。转成视频前必须重新计算相邻事件差值而不是直接拿最后一条事件的时间戳当总时长。let lastActive events[0].timestamp; const compressed []; for (const ev of events) { const gap ev.timestamp - lastActive; if (gap config.threshold) { const fakeGap Math.max(50, Math.round(gap / config.ratio)); const prev compressed[compressed.length - 1]; compressed.push({ ...prev, timestamp: prev.timestamp fakeGap }); } compressed.push(ev); lastActive ev.timestamp; }代码逻辑遍历所有事件遇到超过 threshold 的空闲段就插入一条虚拟事件把时间轴推进 compressIdle.ratio 分之一。这样用户离开 10 分钟视频里只剩 30 秒但画面停留状态还在。fakeGap 最小值设为 50ms是为了避免压缩后时间倒序或相邻事件时间戳完全相等这两个问题都会让回放引擎报错。坑点在于空闲压缩不是对每条事件做等比例缩放而是只压缩「没有事件发生的区间」。用户打字时每击键之间可能只有 300ms这个 gap 小于 threshold不会被压缩用户离开去开会 5 分钟这个 gap 才会被处理。所以 threshold 设置非常关键低于 2000ms 会把正常思考停顿也压掉回放看起来像快进高于 10000ms 则压缩效果微弱。另一个隐蔽问题鼠标移动事件在 rrweb 里是高频的每几十毫秒一条。如果你简单压缩大数据段这段内的鼠标轨迹也会被压缩甚至丢失。常见做法是把空闲段的压缩只应用在最后一个鼠标移动事件之后或者干脆把整个会话的鼠标轨迹做降采样只保留关键转折点。对客服质检来说鼠标轨迹丢失不可接受建议 threshold 保持到 3000ms 以上让轨迹尽量完整。4.3 音画同步与移动端兼容性的取舍rrweb-to-video 多数场景是无声的但如果录制端同时采集了麦克风或 tab 音频事件流会包含音频数据。音画同步依赖的不是 MediaRecorder 自动处理而是录音时间基和回放时间基一致。麦克风采集用的是 AudioContext.currentTime回放框架用的是事件时间戳两者各自漂移录制超过 5 分钟后误差会到几百毫秒。常见做法是录完后用 ffmpeg 对齐音轨ffmpeg -i source.webm -i audio.wav \ -filter_complex [0:v]setptsPTS-STARTPTS[v];[1:a]adelay800|800[a] \ -map [v] -map [a] -c:v libx264 -pix_fmt yuv420p output.mp4这里不太建议把音频延迟写死。正确顺序是先用 ffprobe 看两个文件各自的起始时间再计算偏移我一般用 ffmpeg 的 -fflags genpts 重新生成时间戳再用同步音轨的方式保证对齐。如果你对音画同步要求不高比如只做质检回放音轨偏差在 1 秒内可接受直接去掉音频更省事。移动端是另一层问题。Safari 的 MediaRecorder 对 mp4 封装支持很弱h264 输出基本不可用产物大概率是 webm 或直接报 NotSupportedError。如果你的转换服务跑在服务端移动端兼容性不影响但如果用户直接在自己手机上跑转换脚本建议尽早提示 iOS 走服务端转换链路。这个限制不是参数能绕过去的是底层编码器的差异。5. 转换避坑rrweb-to-video 常见的四个真实踩坑这部分每一段都是我在实际转换 rrweb 数据时踩过并确认原因的问题。现象、原因、解决三步写清楚你可以对照自己的日志逐条排查。5.1 导出的视频有声音没画面现象视频文件时长正常有音轨但画面全程黑屏或只有第一帧画面。原因canvas 没有持续重绘captureStream 拿不到新帧MediaRecorder 录成了黑帧。这在「用户停留在页面两分钟没操作」的长尾会话里最常见因为事件流里没有新事件触发 canvas 绘制浏览器就不产生新帧。解决在回放循环里加一个固定间隔的绘制函数不管有没有新事件都重绘当前帧setInterval(() { renderCurrentFrame(); }, 1000 / fps);加上后验证方式很简单把视频某一帧导出为图片如果画面内容和最后停留状态一致说明修复生效。这个坑是 z-index 的布局变化导致的canvas 被覆盖后 captureStream 依然输出图层内容所以也可能是画布本身绘制异常用 setInterval 强制重绘能同时排查两种情况。5.2 视频时长和实际操作时间差出一大截现象用户实际操作 5 分钟转出来视频 2 小时或者反过来用户操作 2 小时转出来只有 3 分钟。原因直接把事件流里的绝对时间戳当视频时间轴用。rrweb 里增量事件的 timeOffset 是相对字段某些封装版本里还混用了 Unix 毫秒时间戳和相对时间两者一起算会把时间轴拉成一个随机数。解决统一用相邻事件的时间戳差值计算视频总时长不要信任任何单条事件的绝对时间戳。脚本里先把所有 events 按 timestamp 排序清除掉所有 timestamp 倒序的事件再去掉 idle 段。排序这一步必须在转码前做因为录制端有时会因为网络重连导致事件乱序不排序会让时间轴来回跳动。5.3 iframe 和跨域资源在产物里凭空消失现象在浏览器里回放 rrweb 数据完全正常但转成视频后 iframe 区域白屏远程字体图标缺失个别图片显示为裂图。原因rrweb 录制时默认不录制跨域 iframe 的内容要显式配置 recordCrossOriginIframe 才行。转换环境里原 iframe 指向的第三方服务可能已经反爬、改版或挂了回放时拿不到内容转出来自然是空白的。解决两个层面处理。录制端开启 recordCrossOriginIframe转换端设 inlineAssets: true把 CSS、字体、图片都内联成 data URL。如果原数据里本来就没有 iframe 内容转换端补不出来不要浪费时间直接退回到录屏兜底方案。这里诚实说rrweb 对跨域 iframe 的录制支持一直是弱项依赖它做核心证据链有一定风险。5.4 转 mp4 后时长对不上或颜色偏绿现象webm 产物播放正常ffmpeg 转 mp4 后时长少了最后几秒画面颜色发绿或偏紫。原因webm 是 vp9 编码ffmpeg 直接转 h264 时没有指定像素格式默认产出 yuv444p而很多播放器只支持 yuv420p颜色就不对。时长丢失是因为源文件最后一段没有关键帧转码器丢弃了不可解码的部分。解决转码时显式指定像素格式和参数ffmpeg -fflags genpts -i source.webm \ -c:v libx264 -pix_fmt yuv420p -movflags faststart \ output.mp4这组参数里-fflags genpts 强制重新生成时间戳-pix_fmt yuv420p 解决颜色问题-movflags faststart 让 mp4 可以在线播放不加载完就能拖动进度条。转完再用 ffprobe 验证 codec_name 是 h264时长误差在 500ms 内这两项都过了再进交付流程。6. 进阶把转码封装成支持空闲压缩的 HTTP 小服务在生产环境里events 数据通常存在对象存储或数据库里转换是异步任务直接把 node 脚本发给同事跑总有人改参数、改输出路径最后产物对不上。我的做法是把它包成一个 Express 服务输入为 events 与配置输出为任务 ID后台转换完成后回调。这样参数校验、日志收集、失败重试都收在一个地方。const express require(express); const { toVideo } require(rrweb-to-video); const app express(); app.use(express.json({ limit: 100mb })); app.post(/convert, async (req, res) { const { events, output out.mp4, fps 30, idleThreshold 5000 } req.body; const jobId Date.now().toString(36) Math.random().toString(36).slice(2, 6); setTimeout(() convertJob(jobId, { events, output, fps, idleThreshold }), 0); res.json({ jobId }); }); async function convertJob(jobId, cfg) { await toVideo({ events: cfg.events, output: jobs/${cfg.output}, fps: cfg.fps, compressIdle: { threshold: cfg.idleThreshold, ratio: 20 }, }); } app.listen(3000);逻辑说明接口接收 events 数组和三个配置项用时间戳加随机串生成 jobIdsetTimeout 0 让接口立即返回任务 ID实际转换在后台执行。这样前端只需要轮询一个查询接口就能拿到转换状态不会因为长时间转换把 HTTP 连接挂死。参数校验建议加在接口层检查 events 是数组、第一个事件 type 为 0、所有 timestamp 都是数字。这三项过了基本能排除大多数脏数据。额外建议把 mimeType 固定成 h264并在 convertJob 里加一次 ffprobe 验证失败就自动重试一次重试仍失败就把 jobId 和错误信息写入失败日志人肉排查时不用去翻 node 进程日志。从那以后我每次批量导视频都强制走一遍先校验 events 格式再检验产物编码是不是真的 h264最后在样本上做一次空闲压缩验证。别怕多花这几分钟比起几百个文件交付后被打回这几分钟是我买过最值的后悔药。希望帮到你。本文还有配套的精品资源点击获取
