425 lines
9.2 KiB
Markdown
Executable File
425 lines
9.2 KiB
Markdown
Executable File
# Chrome DevTools 与 CDP 协议完全指南
|
||
|
||
> Chrome DevTools 开发者工具 + Chrome DevTools Protocol (CDP) 协议深度研究
|
||
>
|
||
> 归档：2026-04-25
|
||
|
||
---
|
||
|
||
## 📊 生态概览
|
||
|
||
| 项目 | Stars | 定位 |
|
||
|------|-------|------|
|
||
| **Puppeteer** | 94,185 | Google 官方 Node.js CDP 库 |
|
||
| **Playwright** | 87,219 | 微软多浏览器自动化框架 |
|
||
| **go-rod/rod** | 6,881 | Go 语言 CDP 驱动 |
|
||
| **CDP 协议仓库** | 1,476 | 官方协议定义 |
|
||
| **cdpnetool** | 336 | CDP 网络调试工具 |
|
||
| **ichrome** | 259 | Python CDP 控制器 |
|
||
|
||
---
|
||
|
||
## 🎯 Chrome DevTools 是什么
|
||
|
||
**Chrome DevTools** 是 Chrome/Chromium 浏览器内置的**开发者调试工具集**，提供：
|
||
- DOM/CSS 检查与编辑
|
||
- JavaScript 调试与性能分析
|
||
- 网络请求监控与拦截
|
||
- 内存泄漏检测
|
||
- 移动端模拟
|
||
|
||
**底层协议：CDP（Chrome DevTools Protocol）**
|
||
|
||
CDP 是 DevTools 的**通信协议**，允许外部工具通过 WebSocket 与浏览器交互，实现：
|
||
- 自动化测试
|
||
- 网页爬取
|
||
- 性能监控
|
||
- 安全审计
|
||
|
||
---
|
||
|
||
## 🔌 CDP 协议架构
|
||
|
||
### 核心概念
|
||
|
||
```
|
||
外部工具（Puppeteer/Playwright/自定义）
|
||
↓ WebSocket
|
||
Chrome DevTools Protocol (CDP)
|
||
↓
|
||
Chromium 浏览器内核
|
||
```
|
||
|
||
- **Domain（域）**：功能分类（Network、DOM、Page 等）
|
||
- **Command（命令）**：工具→浏览器的请求
|
||
- **Event（事件）**：浏览器→工具的通知
|
||
- **Type（类型）**：数据结构定义
|
||
|
||
### 协议版本
|
||
|
||
| 版本 | 说明 | 适用场景 |
|
||
|------|------|---------|
|
||
| **latest (tot)** | 最新版本，频繁变更 | 最新功能探索 |
|
||
| **v8-inspector** | Node.js 调试专用 | Node.js 调试 |
|
||
| **stable 1.3** | Chrome 64 锁定，向后兼容 | 生产环境 |
|
||
|
||
---
|
||
|
||
## 📦 45+ 核心 Domain 分类
|
||
|
||
### 🔍 页面与 DOM
|
||
|
||
| Domain | 核心能力 |
|
||
|--------|---------|
|
||
| **Page** | 页面导航、截图、打印、生命周期管理 |
|
||
| **DOM** | DOM 树查询、修改、监听变化 |
|
||
| **DOMSnapshot** | 获取完整 DOM 快照 |
|
||
| **DOMDebugger** | DOM 事件断点 |
|
||
| **DOMStorage** | localStorage/sessionStorage 操作 |
|
||
|
||
### 🌐 网络
|
||
|
||
| Domain | 核心能力 |
|
||
|--------|---------|
|
||
| **Network** | 请求/响应拦截、修改、性能分析 |
|
||
| **Fetch** | 请求级拦截与修改（Mock API） |
|
||
| **Security** | 证书、HTTPS、安全状态 |
|
||
| **ServiceWorker** | SW 注册/注销/调试 |
|
||
|
||
### ⚡ 调试与性能
|
||
|
||
| Domain | 核心能力 |
|
||
|--------|---------|
|
||
| **Runtime** | JS 执行、对象检查、异常捕获 |
|
||
| **Debugger** | 断点、单步执行、调用栈 |
|
||
| **Profiler** | CPU 性能分析 |
|
||
| **HeapProfiler** | 内存堆分析、泄漏检测 |
|
||
| **Performance** | 性能指标采集 |
|
||
| **Tracing** | 底层追踪数据 |
|
||
|
||
### 📱 模拟与仿真
|
||
|
||
| Domain | 核心能力 |
|
||
|--------|---------|
|
||
| **Emulation** | 设备模拟、屏幕尺寸、地理位置 |
|
||
| **Input** | 模拟鼠标/键盘/触摸输入 |
|
||
| **DeviceOrientation** | 模拟设备方向 |
|
||
|
||
### 🎨 样式与渲染
|
||
|
||
| Domain | 核心能力 |
|
||
|--------|---------|
|
||
| **CSS** | 样式表查询、修改、计算样式 |
|
||
| **Overlay** | 高亮元素、网格线、滚动条 |
|
||
| **LayerTree** | 渲染层分析 |
|
||
| **Animation** | 动画检查与控制 |
|
||
|
||
### 🔧 其他
|
||
|
||
| Domain | 核心能力 |
|
||
|--------|---------|
|
||
| **Browser** | 浏览器级操作（版本、窗口管理） |
|
||
| **Target** | Tab/Worker 管理 |
|
||
| **Log** | 控制台日志捕获 |
|
||
| **Console** | 控制台消息 |
|
||
| **IO** | 流式数据读写 |
|
||
| **Storage** | Cookie、IndexedDB、Cache |
|
||
|
||
---
|
||
|
||
## 💻 常用 CDP 命令速查
|
||
|
||
### 页面操作
|
||
|
||
```javascript
|
||
// 导航到页面
|
||
Page.navigate({ url: 'https://example.com' })
|
||
|
||
// 截图
|
||
Page.captureScreenshot({ format: 'png' })
|
||
|
||
// 打印为 PDF
|
||
Page.printToPDF({
|
||
landscape: false,
|
||
displayHeaderFooter: true
|
||
})
|
||
```
|
||
|
||
### 网络拦截
|
||
|
||
```javascript
|
||
// 启用网络域
|
||
Network.enable()
|
||
|
||
// 拦截并修改请求
|
||
Fetch.enable({
|
||
patterns: [{ urlPattern: '*', requestStage: 'Request' }]
|
||
})
|
||
|
||
// 修改请求头
|
||
Fetch.continueRequest({
|
||
requestId,
|
||
headers: [{ name: 'User-Agent', value: 'Custom' }]
|
||
})
|
||
|
||
// Mock 响应
|
||
Fetch.fulfillRequest({
|
||
requestId,
|
||
responseCode: 200,
|
||
body: btoa(JSON.stringify({ mock: true }))
|
||
})
|
||
```
|
||
|
||
### JS 执行
|
||
|
||
```javascript
|
||
// 执行 JS
|
||
Runtime.evaluate({
|
||
expression: 'document.title'
|
||
})
|
||
|
||
// 设置断点
|
||
Debugger.enable()
|
||
Debugger.setBreakpoint({
|
||
location: {
|
||
scriptId: '1',
|
||
lineNumber: 10
|
||
}
|
||
})
|
||
```
|
||
|
||
### 设备模拟
|
||
|
||
```javascript
|
||
// 模拟 iPhone
|
||
Emulation.setDeviceMetricsOverride({
|
||
width: 375,
|
||
height: 812,
|
||
deviceScaleFactor: 3,
|
||
mobile: true
|
||
})
|
||
|
||
// 模拟地理位置
|
||
Emulation.setGeolocationOverride({
|
||
latitude: 39.9042,
|
||
longitude: 116.4074
|
||
})
|
||
```
|
||
|
||
### DOM 操作
|
||
|
||
```javascript
|
||
// 获取 DOM 树
|
||
DOM.getDocument({ depth: 2 })
|
||
|
||
// 查询元素
|
||
DOM.querySelector({
|
||
nodeId: 1,
|
||
selector: '.my-class'
|
||
})
|
||
|
||
// 修改属性
|
||
DOM.setAttributeValue({
|
||
nodeId: 42,
|
||
name: 'class',
|
||
value: 'new-class'
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 主流 CDP 库对比
|
||
|
||
### Puppeteer（官方推荐）
|
||
|
||
```javascript
|
||
const puppeteer = require('puppeteer');
|
||
|
||
const browser = await puppeteer.launch();
|
||
const page = await browser.newPage();
|
||
await page.goto('https://example.com');
|
||
await page.screenshot({ path: 'example.png' });
|
||
await browser.close();
|
||
```
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **语言** | Node.js |
|
||
| **维护** | Google 官方 |
|
||
| **Stars** | 94k+ |
|
||
| **适合** | 爬虫、截图、自动化测试 |
|
||
|
||
### Playwright（多浏览器）
|
||
|
||
```javascript
|
||
const { chromium } = require('playwright');
|
||
|
||
const browser = await chromium.launch();
|
||
const page = await browser.newPage();
|
||
await page.goto('https://example.com');
|
||
// 同时支持 Chromium / Firefox / WebKit
|
||
```
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **语言** | JS/Python/Java/.NET |
|
||
| **维护** | 微软 |
|
||
| **Stars** | 87k+ |
|
||
| **适合** | 跨浏览器 E2E 测试 |
|
||
|
||
### go-rod（Go 语言）
|
||
|
||
```go
|
||
package main
|
||
|
||
import "github.com/go-rod/rod"
|
||
|
||
func main() {
|
||
page := rod.New().MustConnect().MustPage("https://example.com")
|
||
page.MustElement("input").MustInput("hello")
|
||
page.MustScreenshot("example.png")
|
||
}
|
||
```
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **语言** | Go |
|
||
| **Stars** | 6.8k |
|
||
| **适合** | Go 生态、高性能爬虫 |
|
||
|
||
### ichrome（Python）
|
||
|
||
```python
|
||
import asyncio
|
||
from ichrome import AsyncChrome
|
||
|
||
async def main():
|
||
async with AsyncChrome() as chrome:
|
||
tab = await chrome.connect_tab(0)
|
||
await tab.goto('https://example.com')
|
||
await tab.screenshot(path='example.png')
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **语言** | Python |
|
||
| **Stars** | 259 |
|
||
| **适合** | Python 爬虫、自动化 |
|
||
|
||
---
|
||
|
||
## 🎯 典型应用场景
|
||
|
||
### 1. 网页自动化
|
||
|
||
```
|
||
场景：自动填写表单、点击按钮、爬取数据
|
||
方案：Puppeteer / Playwright
|
||
关键 API：Page.navigate, Page.click, Page.type
|
||
```
|
||
|
||
### 2. 网络请求拦截
|
||
|
||
```
|
||
场景：Mock API 响应、修改请求头
|
||
方案：Fetch Domain
|
||
关键 API：Fetch.enable, Fetch.fulfillRequest
|
||
```
|
||
|
||
### 3. 性能分析
|
||
|
||
```
|
||
场景：检测页面加载性能、内存泄漏
|
||
方案：Performance + HeapProfiler Domain
|
||
关键 API：Performance.getMetrics, HeapProfiler.takeHeapSnapshot
|
||
```
|
||
|
||
### 4. 移动端测试
|
||
|
||
```
|
||
场景：模拟手机设备访问
|
||
方案：Emulation Domain
|
||
关键 API：Emulation.setDeviceMetricsOverride
|
||
```
|
||
|
||
### 5. 安全审计
|
||
|
||
```
|
||
场景：检测 XSS、检查 HTTPS
|
||
方案：Security + DOMDebugger Domain
|
||
关键 API：Security.getSecurityState, DOMDebugger.setDOMBreakpoint
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发调试技巧
|
||
|
||
### 启用 Protocol Monitor
|
||
|
||
1. 打开 DevTools → 设置 ⚙️
|
||
2. Experiments → 启用 "Protocol Monitor"
|
||
3. More Tools → Protocol monitor
|
||
4. 查看所有 CDP 命令和响应
|
||
|
||
### 直接发送 CDP 命令
|
||
|
||
```
|
||
# 截图
|
||
Page.captureScreenshot
|
||
|
||
# 带参数
|
||
{"cmd":"Page.captureScreenshot","args":{"format":"jpeg"}}
|
||
```
|
||
|
||
### 远程调试
|
||
|
||
```bash
|
||
# 启动 Chrome 远程调试
|
||
chrome --remote-debugging-port=9222
|
||
|
||
# 连接 WebSocket
|
||
ws://localhost:9222/devtools/page/<pageId>
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 CDP 在 AI 编程中的应用
|
||
|
||
| 场景 | CDP 的作用 |
|
||
|------|-----------|
|
||
| **Superpowers 代码审查** | 通过 CDP 检查页面实际渲染效果 |
|
||
| **AI 自动化测试** | 控制浏览器执行 E2E 测试 |
|
||
| **网页爬取** | 动态渲染页面的内容提取 |
|
||
| **性能优化建议** | CDP 采集真实性能数据 |
|
||
| **安全扫描** | 自动检测前端安全问题 |
|
||
|
||
---
|
||
|
||
## 🔗 资源
|
||
|
||
| 资源 | 链接 |
|
||
|------|------|
|
||
| **CDP 官方文档** | https://chromedevtools.github.io/devtools-protocol/ |
|
||
| **Getting Started with CDP** | https://github.com/aslushnikov/getting-started-with-cdp |
|
||
| **awesome-chrome-devtools** | https://github.com/ChromeDevTools/awesome-chrome-devtools |
|
||
| **Puppeteer** | https://github.com/puppeteer/puppeteer |
|
||
| **Playwright** | https://github.com/microsoft/playwright |
|
||
| **go-rod** | https://github.com/go-rod/rod |
|
||
| **cdpnetool** | https://github.com/241x/cdpnetool |
|
||
|
||
---
|
||
|
||
## 💡 与 OpenClaw 的结合点
|
||
|
||
| 结合方式 | 说明 |
|
||
|---------|------|
|
||
| **Browser 工具** | OpenClaw 已通过 Playwright 集成 CDP |
|
||
| **网页自动化** | 可通过 CDP 控制浏览器完成任务 |
|
||
| **性能监控** | CDP 采集数据 → AI 分析建议 |
|
||
| **安全审计** | CDP 检测 → AI 生成报告 |
|
||
|
||
---
|
||
|
||
*整理：知识库管理员 | 归档：2026-04-25* |