Chrome DevTools Protocol 命令构建器 - 生成调试命令

Chrome DevTools Protocol (CDP) 是 Chrome 浏览器提供的一套底层调试接口协议。它允许外部工具（如 Puppeteer、Playwright、Selenium）通过 WebSocket 与 Chrome 通信，实现对浏览器的深度控制——包括页面导航、JavaScript 执行、DOM 操作、网络监控、性能分析、断点调试等。

CDP 是 DevTools 面板背后使用的同一套协议，功能极其强大。通过 CDP，开发者可以精确控制浏览器的每一个行为，实现高级自动化和调试任务。本工具帮助您快速生成 CDP 命令，无需记忆复杂的协议格式和参数结构。

每条 CDP 命令都是一个 JSON 对象，包含三个必要字段：

• id — 整数，用于匹配请求与响应（同一连接中 ID 应唯一）
• method — 字符串，格式为 Domain.methodName，如 Page.navigate
• params — 对象，包含该方法所需的参数（可为空对象 {}）

本工具会自动生成符合此格式的完整命令，确保您可以直接使用。如果需要手动检查格式，可以在预览区域查看格式化的 JSON 输出，所有字段一目了然。

Puppeteer 和 Playwright 都是基于 CDP 构建的高级自动化库。它们封装了 CDP 的底层细节，提供了更友好的 API。同时，它们也暴露了原始 CDP 会话，让开发者可以在需要时直接发送原始 CDP 命令。

例如，在 Puppeteer 中可以通过 page.createCDPSession() 创建 CDP 会话，然后调用 session.send() 发送原始 CDP 命令。本工具生成的 Puppeteer 示例代码展示了这种用法，您可以直接复制到项目中使用。当高级 API 无法满足需求时，直接使用 CDP 是最灵活的解决方案。

最常用的 CDP 域包括：

• Page — 页面导航、截图、打印、生命周期事件监控
• Network — 网络请求监控、拦截、修改和响应分析
• Runtime — JavaScript 执行、表达式求值、内存分析和异常监控
• DOM — DOM 树查询、修改、事件监听和文档操作
• Debugger — 断点设置、代码暂停、步进调试和作用域查看
• Input — 模拟用户输入事件（点击、键盘、鼠标、触摸）
• Emulation — 设备模拟、屏幕尺寸、地理位置和传感器仿真
• Target — 浏览器标签页和 iframe 的创建、管理和通信

本工具支持所有 CDP 域，您可以通过域选择器快速定位到需要的功能分组，每个域下的方法都有简要说明。

使用 Page.captureScreenshot 命令可以截取页面截图。在本工具中的操作步骤：

1. 在域选择器中选择 Page 域
2. 在方法列表中选择 captureScreenshot
3. 在参数区域设置截图选项，如 format（格式：png 或 jpeg）、quality（质量，仅 jpeg 有效）、clip（裁剪区域）等
4. 点击复制按钮获取生成的命令

返回的 result.data 字段包含 Base64 编码的图片数据，可以直接解码保存为图片文件。您还可以设置 returnAsBase64 参数控制返回格式。该功能适用于自动化测试中的视觉回归测试和页面内容记录。

使用本工具生成的 JSON 命令通过 WebSocket 发送的完整步骤：

1. 启动 Chrome 时添加 --remote-debugging-port=9222 参数
2. 访问 http://localhost:9222/json 获取可用页面的 WebSocket URL
3. 使用 WebSocket 客户端（如 wscat、Postman）连接到 WebSocket URL
4. 发送本工具生成的 JSON 命令，即可在浏览器中执行对应操作

例如完整的启动命令：chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

连接成功后，将本工具生成的命令粘贴到 WebSocket 客户端即可执行。请确保在命令执行期间保持 WebSocket 连接处于活动状态，否则浏览器会丢失连接。

id 字段用于将响应与请求进行匹配。CDP 支持异步通信，可以同时发送多条命令，每条的 id 应唯一。

在 WebSocket 通信中，浏览器返回的每条响应都会包含对应的 id 值，这样客户端就能知道每条响应对应哪条请求。如果多个命令使用相同的 id，会导致响应匹配混乱，无法正确处理结果。

本工具提供自动递增的 ID 管理功能，确保每次生成的命令使用唯一的 ID。您也可以手动设置自定义 ID，但请确保在同一连接中不重复使用。建议在多命令场景下使用有规律的 ID 序列，便于日志分析和问题排查。

使用 Emulation.setDeviceMetricsOverride 命令可以设置设备的屏幕尺寸和像素比。配合 Emulation.setUserAgentOverride 可完整模拟移动端环境。

在本工具中的操作步骤：

1. 选择 Emulation 域
2. 选择 setDeviceMetricsOverride 方法
3. 设置宽度（width）、高度（height）、设备缩放因子（deviceScaleFactor）
4. 生成命令后，再选择 setUserAgentOverride 设置移动端 User-Agent 字符串

两个命令配合使用，可以完整模拟各种移动设备的环境。本工具的快捷预设中也提供了常见移动设备（如 iPhone、Android 手机）的模拟配置，一键即可完成设备模拟。