会话录制

当浏览器自动化失败或行为异常时，很难理解发生了什么。会话录制将 DOM 变更、鼠标和键盘事件以及页面导航捕获为结构化 JSON 事件——而非视频——因此轻量且易于检查。录制由 rrweb ↗ 提供支持，按会话选择启用。

向 puppeteer.launch() 或 playwright.launch() 传递 recording: true：

import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const browser = await puppeteer.launch(env.MYBROWSER, { recording: true });
		const page = await browser.newPage();

		await page.goto("https://example.com");
		// ... your automation steps ...

		const sessionId = browser.sessionId();
		await browser.close();

		return new Response(`Session recorded: ${sessionId}`);
	},
};

import { launch } from "@cloudflare/playwright";

interface Env {
	MYBROWSER: Fetcher;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const browser = await launch(env.MYBROWSER, { recording: true });
		const page = await browser.newPage();

		await page.goto("https://example.com");
		// ... your automation steps ...

		const sessionId = browser.sessionId();
		await browser.close();

		return new Response(`Session recorded: ${sessionId}`);
	},
};

从任何环境使用 CDP 端点 连接到 Browser Run 时，在 WebSocket URL 中添加 recording=true 作为查询参数：

wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?recording=true&keep_alive=600000

例如，要在 MCP 客户端中启用会话录制，在客户端配置的 --wsEndpoint URL 中添加 recording=true：

{
	"mcpServers": {
		"browser-rendering": {
			"command": "npx",
			"args": [
				"-y",
				"chrome-devtools-mcp@latest",
				"--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?recording=true&keep_alive=600000",
				"--wsHeaders={\"Authorization\":\"Bearer <API_TOKEN>\"}"
			]
		}
	}
}

有关其他 MCP 客户端以及通过 Puppeteer 或 Playwright 使用 CDP 的信息，请参阅 CDP 文档。

会话关闭后，其录制可在 Cloudflare 仪表板的 Browser Run > **Runs（运行记录）**下查看。选择会话旁的录制图标以打开录制查看器，你可以拖动（scrub）时间线并回放会话期间发生的内容。

如果会话打开了多个标签页，录制查看器会在回放区域右上角显示标签页选择器下拉菜单。使用它切换已录制的标签页并单独查看每个标签页的活动。

你也可以使用会话 ID 以编程方式检索录制。在关闭浏览器之前使用 browser.sessionId() 捕获会话 ID，然后将其传递给录制端点。

curl https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/recording/<SESSION_ID> \
  -H "Authorization: Bearer <API_TOKEN>"

成功响应类似如下：

{
	"sessionId": "e26d4660-5b78-4761-b82f-c6b5bad5a925",
	"duration": 4380,
	"events": {
		"target-1": [],
		"target-2": []
	}
}

events 中的键（如 target-1、target-2）是 CDP target ↗。在会话录制的上下文中，每个 target 通常对应一个浏览器标签页。打开多个标签页的会话将每个标签页对应一个 target，每个 target 的值是该标签页的独立 rrweb 事件数组。

events 中的每个值都是标准 rrweb 事件数组，可直接传递给 rrweb-player ↗ 以自托管带有时间线 scrubber 和播放控件的回放 UI。

标签页独立回放——要回放多标签页会话，为每个 target 渲染一个播放器，或构建允许用户在 target 之间切换的 UI（类似于仪表板录制查看器中的标签页选择器）。

• 录制在会话结束后保留 30 天，然后自动删除。
• 录制为选择启用。默认未启用。
• 会话录制可通过 launch() 和 CDP 端点 用于浏览器会话。Quick Actions 不支持。
• 最短录制时长为 1 秒。短于 1 秒的会话不会产生可查看的录制。
• 最长录制时长为 2 小时。

会话录制使用 rrweb ↗，它记录 DOM 状态和事件而非像素。此方法轻量但存在以下限制：

• Canvas 元素 — 不会捕获 <canvas> 元素的内容。元素本身在录制中显示为空白占位符。
• 跨源 iframe — 不会录制跨源 <iframe> 元素内的内容。同源 iframe 正常录制。
• 视频和音频 — 会捕获 <video> 和 <audio> 元素的 DOM 结构，但不会捕获媒体播放状态和内容。
• WebGL — 不会捕获 WebGL 渲染。
• 输入字段 — 所有输入字段的内容默认被掩码，在回放中不可见。
• 大型或复杂页面 — 频繁 DOM 变更的页面（例如具有实时数据源或重度动画的页面）可能生成大量事件，从而增加录制大小。