# 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*