跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Live View

最后更新 查看 MarkdownAgent 设置

Live View 让你实时查看和交互远程 Browser Run 会话。这对于调试自动化脚本、监控浏览器正在执行的操作,或在任务需要人工干预时手动介入很有用(请参阅 Human in the Loop)。

Live View 适用于任何 Browser Session,包括使用 Puppeteer、Playwright 或 Chrome DevTools Protocol (CDP) 端点创建的会话。

浏览器会话是一个远程 Chrome 实例。一个会话可以包含多个标签页。CDP 将每个可调试项称为 target,page target 通常表示一个浏览器标签页。Live View 连接到 page target。

访问 Live View

从 Cloudflare 仪表板或使用生成的 devtoolsFrontendUrl 打开 Live View。生成的 URL 会在任何浏览器中打开 Cloudflare 托管的界面。Chrome 用户也可以在 Chrome DevTools 中打开该连接。

Cloudflare 仪表板

在 Cloudflare 仪表板中,前往 Browser Run 页面并选择 Live Sessions(实时会话) 选项卡。这将显示账户中所有活动的浏览器会话。展开会话以查看其标签页,然后选择 Open(打开) 打开该标签页的 Live View。

前往 Browser Run ↗

生成的 URL(任意浏览器)

使用 targets=true 创建会话或列出会话的 target 时,API 响应为每个 page target 包含 devtoolsFrontendUrl。在任何浏览器中打开此 URL,通过 Cloudflare 托管界面监视或控制该标签页。生成的 URL 使用 live.browser.run;你无需直接访问该主机名。

托管 UI 支持三种查看模式,由 URL 中的 mode 参数控制:

模式 URL 模式 描述
tab https://live.browser.run/ui/view?mode=tab&wss=... 显示并控制一个选定页面,不包含 DevTools 面板
full https://live.browser.run/ui/view?mode=full&wss=... 显示浏览器界面及其打开的页面标签页
devtools https://live.browser.run/ui/view?mode=devtools&wss=... 为一个页面打开 DevTools 面板,包括 Elements 和 Console

原生 Chrome DevTools(仅 Chrome)

Browser Run 支持为 Chrome DevTools 提供能力的协议 CDP。如果生成的 devtoolsFrontendUrl 以 https://live.browser.run/ui/inspector?wss= 开头,将该前缀替换为 devtools://devtools/bundled/inspector.html?wss=:

devtools://devtools/bundled/inspector.html?wss=live.browser.run/api/devtools/browser/SESSION_ID/page/TARGET_ID?jwt=...

将更新后的 URL 粘贴到 Chrome 地址栏。Chrome 会为远程标签页打开其内置 DevTools 界面。devtools:// 协议仅适用于 Chrome,且仅支持 devtools 查看模式。

后续章节中的 API 示例假定已设置 $ACCOUNT_ID,且 $CLOUDFLARE_API_TOKEN 具有 Browser Rendering Write 权限。

查看新会话

  1. 使用 targets=true 创建浏览器会话,以在响应中包含其当前 page target 和生成的 Live View URL:
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser?keep_alive=600000&targets=true" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"sessionId": "1909cef7-23e8-4394-bc31-27404bf4348f",
	"targets": [
		{
			"description": "",
			"devtoolsFrontendUrl": "https://live.browser.run/ui/inspector?wss=live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=...",
			"id": "8E598E996530FB09E46A22B8B7754F7F",
			"title": "about:blank",
			"type": "page",
			"url": "about:blank",
			"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=..."
		}
	],
	"webSocketDebuggerUrl": "wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/1909cef7-..."
}

targets[].devtoolsFrontendUrl 打开页面的托管界面。targets[].webSocketDebuggerUrl 将 CDP 客户端连接到该页面。顶层 webSocketDebuggerUrl 将 CDP 客户端连接到浏览器会话。

  1. 通过 title 或 url 找到你想要的 page target。复制其 devtoolsFrontendUrl 并在浏览器中打开。新会话最初包含一个 about:blank 页面。

查看现有会话

如果你有正在运行的会话并想连接到它:

  1. 列出活动会话并复制要查看的会话 ID:

    curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/session" \
    	--request GET \
    	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
  2. 使用会话 ID 列出该会话中的 target:

    curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/json/list" \
    	--request GET \
    	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
    [
    	{
    		"id": "110850A800BDB8B593CDDA30676635CF",
    		"type": "page",
    		"url": "https://example.com",
    		"title": "Example Domain",
    		"description": "",
    		"devtoolsFrontendUrl": "https://live.browser.run/ui/view?wss=live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=...",
    		"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=..."
    	}
    ]
  3. 复制 devtoolsFrontendUrl 并在浏览器中打开。

生成 Live View URL

列出 target 会为每个 page target 返回默认的 devtoolsFrontendUrl。生成自定义 URL 以更改查看模式、连接截止时间或查看者权限。

设置参数

以下可选参数配置生成的链接:

参数 类型 默认值 描述
mode string devtools 查看模式:devtools、tab 或 full
expiresInMs number 300,000(五分钟) 开始连接的截止时间(毫秒)。最小 60,000,最大 3,600,000
targetId string 当前 CDP target 或第一个 page target 要查看的 page target
guardrails object — 仅 REST API。此连接的查看者限制。设置 { "mode": "readonly" } 以阻止交互

REST API 响应包含 id、options、devtoolsFrontendUrl 和 webSocketDebuggerUrl。在浏览器中打开前端 URL,或将 WebSocket URL 与 CDP 客户端一起使用。Cloudflare.getLiveView CDP 命令返回 devtoolsFrontendUrl。

只读 Live View guardrail 仅应用于生成的连接。其他连接和自动化脚本仍可控制会话。会话 guardrails 限制整个会话的 HTTP 和 HTTPS 目标,并对每个 Live View 连接保持生效。

REST API

使用 Live View 端点 生成 URL:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/live_view" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"mode": "tab",
		"expiresInMs": 300000
	}'

共享仅查看链接

要阻止查看者交互,将 guardrails 设置为 { "mode": "readonly" }:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/live_view" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"mode": "tab",
		"guardrails": {
				"mode": "readonly"
		}
	}'

该链接会流式传输会话,但阻止导航、输入和 JavaScript 求值。标签页标题以 READ ONLY - 开头。

CDP

CDP 是 Chrome 的远程调试协议。Cloudflare.getLiveView 是 Cloudflare 扩展,可在现有 CDP 连接上生成 Live View URL。此 Puppeteer 示例为当前页面生成 URL:

export async function getLiveViewUrl(page) {
	const cdp = await page.createCDPSession();

	const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", {
		mode: "tab",
		expiresInMs: 300000,
	});

	return devtoolsFrontendUrl;
}
import type { Page } from "@cloudflare/puppeteer";

export async function getLiveViewUrl(page: Page): Promise<string> {
	const cdp = await page.createCDPSession();

	const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", {
		mode: "tab",
		expiresInMs: 300000,
	});

	return devtoolsFrontendUrl;
}

要将 Live View 用于人工操作员交接,请参阅 Human in the Loop 工作流。

这篇文档对您有帮助吗?