高级回放与故障排查

当你的应用已经能够安全地获取完整的 rrweb 事件数组之后，再使用本指南。本指南涵盖回放层；事件摄取与查看者授权是独立的关注点。

以编程方式控制播放

rrwebPlayer 暴露了 play()、pause()、goto()、setSpeed() 和 toggleSkipInactive() 等用于构建自定义控件的 UI 方法，以及用于直接访问底层 Replayer 的 getReplayer()。

javascript

player.play();
player.pause();
player.goto(30_000, false);
player.setSpeed(2);
player.toggleSkipInactive();

player.addEventListener('ui-update-current-time', ({ payload }) => {
  updateClock(payload);
});

需要底层 Replayer 的事件或方法时，使用 player.getReplayer()；视图卸载时调用 player.$destroy()。

继续在 rrweb Library 的自定义回放器界面配方中了解控制器事件、尺寸调整和自定义 UI 模式，或查阅 rrweb-player 包参考了解完整的公开 API。

配置 Replayer

props 中不属于播放器专用选项的配置会传递给底层的 Replayer。请从一个小而明确的配置开始：

javascript

const player = new rrwebPlayer({
  target: document.querySelector('#replay'),
  props: {
    events,
    autoPlay: false,
    showController: true,
    skipInactive: true,
    mouseTail: false,
    triggerFocus: false,
    showWarning: true,
    showDebug: false,
  },
});

录制时的隐私设置无法在回放期间恢复。屏蔽、脱敏、canvas 捕获、样式表内联和资源捕获都必须在录制时配置；参见录制与隐私设置。

在启用 canvas 回放或注入样式等选项之前，请先在 rrweb Library 的回放选项中继续阅读。

对于无 UI 的播放，改为直接实例化 @rrweb/replay 中的 Replayer。继续在 rrweb Library 的 @rrweb/replay 包参考中了解安装、样式和直接 API。

在回放期间处理自定义事件

自定义事件无需定义回放插件即可描述应用特定的时刻。使用浏览器客户端的 addCustomEvent(tag, payload) 记录一个小型、带版本号的负载，然后通过播放器底层的 Replayer 监听该事件：

javascript

const replayer = player.getReplayer();

replayer.on('custom-event', (event) => {
  if (event.tag === 'checkout-completed') {
    showOrderMarker(event.payload);
  }
});

要在 rrweb-player 时间线上显示相同的标签，请在初始化播放器时包含 tags 颜色映射：

javascript

const player = new rrwebPlayer({
  target: replayTarget,
  props: {
    events,
    tags: {
      'checkout-completed': '#2563eb',
    },
  },
});

不要在自定义事件的负载中放入机密信息或原始用户输入。

继续在 rrweb Library 的自定义事件配方中了解录制、监听和时间线样式语义。

插件

回放插件必须与其录制侧对应组件发出的数据相匹配。例如，sequential-ID、console、network 和 canvas 集成各自都有独立的录制包和回放包。请锁定兼容的包版本，并在上线前测试确切的录制器/回放器组合。

继续在 rrweb Library 的插件指南中了解插件契约和包目录。

处理大型录制

获取录制事件会返回完整录制的顶层 JSON 数组。它目前不接受 limit 或 offset。请显示加载状态，在查看者切换录制时中止已过时的请求，并在分配新播放器之前销毁旧播放器。

对于由多个录制组成的长用户旅程，Cloud 可以按元数据组合这些录制。不要在不保留 FullSnapshot 边界和时间戳顺序的情况下拼接不相关的事件数组。

如果你自己的受信代理或存储层以分块方式交付已获取的流，Replayer.addEvent() 可以追加有序事件。继续在 rrweb Library 的异步加载事件配方中了解该回放 API。该配方不会为 Cloud 事件端点添加分页参数。

检查 rrweb 版本兼容性

Cloud 存储 rrweb 事件，并将其返回给 rrweb-player 或 Replayer，因此 rrweb 版本和插件兼容性要求仍然适用；升级前请回放一个隐私安全的测试夹具，并验证 FullSnapshot 顺序、插件对齐情况和浏览器渲染。

升级前：

回放一个由已部署录制器捕获的隐私安全测试夹具；
验证每个页面视图都有 FullSnapshot 先于变更出现；
验证回放侧插件与已录制的插件事件相匹配；以及
在目标浏览器中检查样式表、字体、图片、iframe 和 canvas 行为。

让录制器和回放依赖保持在已知兼容的版本上。更新的播放器无法重建从未被捕获的 DOM 或资源数据。

处理缺失或损坏的事件

请将事件流视为有序数据。每个事件都需要有效的 type、 timestamp 和 data 值，增量变更需要相应的先前 FullSnapshot。静默过滤损坏的事件可能导致后续变更指向从未创建的节点。

回放失败时：

检查 HTTP 状态，并确认响应是非空的 JSON 数组；
将事件数量和时间戳与原始摄取日志进行比较；
定位第一个 FullSnapshot，以及来自 showWarning 或临时 showDebug 输出的第一个警告；以及
使用应用所用的相同 rrweb 和插件版本进行复现。

仅在隐私安全的录制上使用诊断日志；事件负载可能包含捕获的页面数据。

rrweb Cloud 支持实时回放吗？

不支持。实时摄取回放 不受 rrweb Cloud 支持：Cloud 的 WebSocket 端点将事件流式传输到存储中，但不会把这些事件流式传回查看者，因此请等到事件可检索后再开始 Cloud 回放。

对于独立运营的端到端实时传输，请在 Cloud 之外继续。继续在 rrweb Library 的实时模式配方中了解。其 liveMode、startLive() 和 addEvent() API 不会将 Cloud 摄取变成实时播放源。

故障排查

症状	检查	操作
获取事件时返回 `401`	查看者未使用凭据或使用了错误的凭据	在受信服务器上获取访问权限或进行签名；公开写入密钥无法读取录制
签名 URL 返回 `403`	过期时间或签名不再有效	重新授权查看者后，请求一个新的受限 URL
空数组或 `404`	录制 ID、组织以及是否已收到事件	在初始化播放器之前，先在仪表板中核实该录制
回放开始时画面空白	FullSnapshot 缺失或过晚	检查事件顺序和录制器的检查点行为
DOM 出现偏差	资源缺失、iframe 限制、不支持的捕获或版本不匹配	使用隐私安全的测试夹具复现，并比较录制器/回放器配置
插件事件不起作用	回放插件缺失或不兼容	安装匹配的回放插件并对齐版本
浏览器变慢	事件数组过大，或旧播放器驻留在内存中	显示加载状态、销毁旧播放器，并减少可选的视觉效果

高级回放与故障排查 ​

以编程方式控制播放 ​

配置 Replayer ​

在回放期间处理自定义事件 ​

插件 ​

处理大型录制 ​

检查 rrweb 版本兼容性 ​

处理缺失或损坏的事件 ​

rrweb Cloud 支持实时回放吗？ ​

故障排查 ​

高级回放与故障排查

以编程方式控制播放

配置 Replayer

在回放期间处理自定义事件

插件

处理大型录制

检查 rrweb 版本兼容性

处理缺失或损坏的事件

rrweb Cloud 支持实时回放吗？

故障排查