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

Chrome DevTools Protocol (CDP) 概览

最后更新 查看 MarkdownAgent 设置

/devtools 端点提供遵循 Chrome DevTools Protocol (CDP) ↗ 的会话管理功能。这些端点允许你创建持久浏览器会话、管理多个标签页,并使用 CDP 命令与浏览器交互。这对于高级自动化、调试和远程浏览器控制很有用。

CDP 端点可从任何支持 WebSocket 连接的环境访问,包括本地开发机器、外部服务器和 CI/CD 流水线。这意味着你可以从 Node.js 脚本、Puppeteer、Playwright 或任何 CDP 兼容客户端连接到 Browser Run。

开始之前,请创建自定义 API Token,并授予 Browser Rendering - Edit 权限。

什么是 CDP?

Chrome DevTools Protocol (CDP) 是一种远程调试协议,允许你对基于 Chromium 的浏览器进行检测、检查、调试和分析。Chrome DevTools 使用相同的协议来控制和监控浏览器。Puppeteer 和 Playwright 等流行的浏览器自动化库在 CDP 之上提供高级 API,使自动化常见任务更加容易。

使用场景

浏览器会话端点使你可以:

  • 创建和管理持久浏览器会话 — 启动长时间保持活动的浏览器实例
  • 打开、关闭和列出浏览器标签页(target) — 在单个浏览器实例中管理多个可调试 target(页面、iframe 等)
  • 通过 WebSocket 发送 CDP 命令 — 以编程方式自动化浏览器操作
  • 使用 Chrome DevTools UI 查看实时浏览器会话 — 可视化调试和检查远程浏览器会话
  • 与现有 CDP 客户端集成 — 使用 Puppeteer 等标准 CDP 客户端或自定义 WebSocket 实现

工作原理

获取浏览器会话后,你可以通过两种方式与其交互:

通过 WebSocket 使用 CDP

连接到 WebSocket 端点 /devtools/browser 以获取会话并通过连接直接发送 CDP 命令 ↗。这是使用 CDP 的标准方式,适用于任何 CDP 客户端,包括 Puppeteer、Playwright 和 MCP 客户端。

HTTP API

还提供 HTTP 端点来管理浏览器生命周期,无需使用 WebSocket。这些遵循标准 CDP HTTP 端点 ↗:

  1. 创建会话 — POST /devtools/browser
  2. 列出标签页 — GET /devtools/browser/{session_id}/json/list
  3. 创建标签页 — PUT /devtools/browser/{session_id}/json/new
  4. 关闭标签页 — DELETE /devtools/browser/{session_id}/json/close/{target_id}
  5. 关闭会话 — DELETE /devtools/browser/{session_id}

查看 API 参考 了解 HTTP 端点。WebSocket 端点及其参数记录在 WebSocket 端点 中。

WebSocket 端点

Browser Run 提供三个 WebSocket 端点。每个端点都需要在 Authorization: Bearer <API_TOKEN> 请求头中提供 API token。

获取并连接到浏览器

使用此端点获取浏览器会话并连接到它:

wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser

路径参数:

参数 类型 必填 描述
account_id string 是 Cloudflare 账户 ID。

查询参数:

参数 类型 必填 默认值 描述
keep_alive number 否 60000 会话生命周期(毫秒)。取值必须在 10000 和 1200000 之间(含边界)。
lab boolean 否 false 设为 true 时使用 Browser Run 的实验性池。这些浏览器实例启用实验性 Chrome 功能,便于在到达稳定版 Chrome 之前进行测试。
recording boolean 否 false 设为 true 时录制浏览器会话。
browser string 否 — 选择浏览器后端。接受的值为 kitesurf。不要与 keep_alive、lab 或 recording 同时使用。

可选请求头:

请求头 描述
cf-brapi-guardrails Base64url 编码的会话 guardrails。JSON 对象可以包含 allowedDomains 和 allowedDomainSets。请参阅 Guardrails。

连接到现有浏览器

使用此端点连接到现有浏览器会话:

wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/{session_id}

路径参数:

参数 类型 必填 描述
account_id string 是 Cloudflare 账户 ID。
session_id string 是 浏览器会话 ID。

查询参数:

参数 类型 必填 默认值 描述
keep_alive number 否 60000 仅在获取会话时生效。取值必须在 10000 和 1200000 之间。
lab boolean 否 false 仅在获取会话时生效。设为 true 时使用 Browser Run 的实验性池。这些浏览器实例启用实验性 Chrome 功能,便于在到达稳定版 Chrome 之前进行测试。
recording boolean 否 false 仅在获取会话时生效。设为 true 时录制浏览器会话。

可选请求头:

请求头 描述
cf-brapi-guardrails Base64url 编码的连接 guardrails。编码前使用 {"mode":"readonly"},可将连接限制为只读 CDP 方法。

连接到页面

使用此端点连接到特定 target 或页面:

wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/{session_id}/page/{target_id}

路径参数:

参数 类型 必填 描述
account_id string 是 Cloudflare 账户 ID。
session_id string 是 浏览器会话 ID。
target_id string 是 Chrome DevTools Protocol target ID。

可选请求头:

请求头 描述
cf-brapi-guardrails Base64url 编码的连接 guardrails。编码前使用 {"mode":"readonly"},可将连接限制为只读 CDP 方法。

故障排除

如有疑问或遇到错误,请参阅 Browser Run 常见问题与故障排除指南。

这篇文档对您有帮助吗?