Chrome DevTools Protocol 实战：用 CDP 构建自动化测试与性能监控工具

Puppeteer 和 Playwright 已经成为前端自动化测试的标配工具，但大多数开发者对它们的底层通信协议——Chrome DevTools Protocol（CDP）——几乎一无所知。根据 Chrome DevTools 团队 2025 年的数据，超过 90% 的 Puppeteer 用户从未直接使用过 CDP 命令，这意味着他们错过了 CDP 提供的大量高级能力：精确的性能追踪、内存快照分析、WebSocket 实时监控、自定义覆盖（Override）等。理解 CDP 不是学术兴趣，而是构建超越现成工具的自定义自动化方案的工程基础。

📌 记住： CDP 是一个基于 WebSocket 的 JSON-RPC 协议。所有 Puppeteer、Playwright 的操作最终都会转化为 CDP 命令发送给 Chrome。直接使用 CDP 意味着你能访问浏览器的全部调试能力，而不只是封装库暴露的子集。

🔌 一、CDP 协议架构与连接方式

1.1 CDP 的分层设计

CDP 协议按照功能域（Domain）组织，每个域提供一组相关的方法（Method）和事件（Event）。截至 Chrome 130+，CDP 包含 40+ 个功能域，涵盖页面控制、网络、性能、安全、存储等各个方面。

1.2 直接连接 CDP

Puppeteer 和 Playwright 隐藏了 CDP 的连接细节。要直接使用 CDP，你需要启动 Chrome 时开启远程调试端口：

# 启动 Chrome 并开启 CDP 远程调试
# --remote-debugging-port 指定 WebSocket 端口
# --headless=new 使用新版无头模式（性能更好）
google-chrome \
  --remote-debugging-port=9222 \
  --headless=new \
  --disable-gpu \
  --no-sandbox

获取 WebSocket 调试 URL：

// connect-cdp.mjs — 获取 CDP WebSocket 端点
// Chrome 启动后，通过 HTTP 接口获取 WebSocket URL
const response = await fetch('http://localhost:9222/json/version')
const { webSocketDebuggerUrl } = await response.json()
console.log('CDP WebSocket URL:', webSocketDebuggerUrl)
// 输出: ws://127.0.0.1:9222/devtools/browser/xxxx-xxxx

1.3 用原生 WebSocket 与 CDP 通信

CDP 协议本质是 JSON-RPC over WebSocket。你可以不依赖任何库，直接用原生 API 通信：

// cdp-client.mjs — 最小化 CDP 客户端实现
// 展示 CDP 协议的本质：JSON-RPC over WebSocket

class CDPClient {
  #ws = null
  #id = 0
  #callbacks = new Map()
  #eventHandlers = new Map()

  async connect(url) {
    return new Promise((resolve, reject) => {
      this.#ws = new WebSocket(url)
      this.#ws.onopen = () => resolve()
      this.#ws.onerror = (e) => reject(e)
      this.#ws.onmessage = (event) => {
        const msg = JSON.parse(event.data)
        // CDP 响应：包含 id 字段
        if (msg.id !== undefined) {
          const cb = this.#callbacks.get(msg.id)
          if (cb) {
            this.#callbacks.delete(msg.id)
            msg.error ? cb.reject(msg.error) : cb.resolve(msg.result)
          }
        }
        // CDP 事件：包含 method 字段
        if (msg.method) {
          const handlers = this.#eventHandlers.get(msg.method) || []
          handlers.forEach(fn => fn(msg.params))
        }
      }
    })
  }

  // 发送 CDP 命令
  send(method, params = {}) {
    const id = ++this.#id
    return new Promise((resolve, reject) => {
      this.#callbacks.set(id, { resolve, reject })
      this.#ws.send(JSON.stringify({ id, method, params }))
    })
  }

  // 监听 CDP 事件
  on(event, handler) {
    if (!this.#eventHandlers.has(event)) {
      this.#eventHandlers.set(event, [])
    }
    this.#eventHandlers.get(event).push(handler)
  }

  close() {
    this.#ws?.close()
  }
}

// 使用示例：导航到页面并获取标题
const cdp = new CDPClient()
await cdp.connect('ws://127.0.0.1:9222/devtools/browser/xxxx')

// 获取第一个 tab 的 target ID
const { targetInfos } = await cdp.send('Target.getTargets')
const page = targetInfos.find(t => t.type === 'page')

// 附加到页面 target
const { sessionId } = await cdp.send('Target.attachToTarget', {
  targetId: page.targetId,
  flatten: true
})

// 在 session 中执行命令（通过 sessionId 区分）
await cdp.send('Page.enable', {}, sessionId)
await cdp.send('Page.navigate', { url: 'https://example.com' }, sessionId)

⚠️ 警告： CDP 的 sessionId 机制是多 tab 管理的关键。每个页面 target 需要单独 attach 并获得独立的 sessionId。发送命令时必须指定 sessionId，否则命令会发送到 browser 级别而非特定页面。这是直接使用 CDP 最容易踩的坑。

🚀 二、实战场景一：网络请求拦截与 Mock

2.1 用 Fetch 域拦截请求

CDP 的 Fetch 域比 Puppeteer 的 page.setRequestInterception() 更强大——它支持修改请求头、响应体、甚至模拟网络错误：

// network-interceptor.mjs — 用 CDP Fetch 域实现请求拦截与 Mock
// 场景：API 自动化测试中，Mock 后端响应

async function setupNetworkMock(cdp, sessionId, mocks) {
  // 启用 Fetch 域，指定拦截模式
  await cdp.send('Fetch.enable', {
    patterns: mocks.map(mock => ({
      urlPattern: mock.urlPattern,     // URL 匹配模式（支持通配符）
      requestStage: 'Request',         // 在请求阶段拦截
      resourceType: 'XHR'             // 只拦截 XHR 请求
    }))
  }, sessionId)

  // 监听请求暂停事件
  cdp.on('Fetch.requestPaused', async (params) => {
    const { requestId, request } = params
    const matchedMock = mocks.find(m =>
      new URLPattern(m.urlPattern).test(request.url)
    )

    if (matchedMock) {
      // 返回 Mock 响应
      const body = btoa(JSON.stringify(matchedMock.response))
      await cdp.send('Fetch.fulfillRequest', {
        requestId,
        responseCode: 200,
        responseHeaders: [
          { name: 'Content-Type', value: 'application/json' },
          { name: 'Access-Control-Allow-Origin', value: '*' }
        ],
        body
      }, sessionId)
    } else {
      // 放行未匹配的请求
      await cdp.send('Fetch.continueRequest', { requestId }, sessionId)
    }
  })
}

// 使用示例
const mocks = [
  {
    urlPattern: '*/api/users/*',
    response: { id: 1, name: '测试用户', role: 'admin' }
  },
  {
    urlPattern: '*/api/config',
    response: { featureFlags: { newUI: true }, version: '2.0.0' }
  }
]

await setupNetworkMock(cdp, sessionId, mocks)
// 之后页面中所有匹配的 API 请求都会返回 Mock 数据

2.2 性能对比：CDP 直连 vs Puppeteer

在大规模爬虫或测试场景中，直接使用 CDP 可以避免 Puppeteer 的封装开销：

💡 提示： 性能差距在小规模场景（<10 个页面）中可以忽略。只有在大规模并发（100+ 页面、每秒 1000+ 请求）场景下，CDP 直连的优势才会显现。对于大多数项目，Puppeteer/Playwright 的便利性远超这点性能差异。

📊 三、实战场景二：性能追踪与指标采集

3.1 用 Tracing 域采集渲染性能

CDP 的 Tracing 域可以捕获 Chrome 内部的全部性能事件，生成标准的 Trace Event 格式文件，用 Chrome DevTools 的 Performance 面板直接打开分析：

// perf-tracer.mjs — 用 CDP Tracing 域采集页面性能数据
// 生成 .json 文件可直接在 chrome://tracing 中打开

async function capturePerformanceTrace(cdp, sessionId, url) {
  // 1. 启用必要的域
  await cdp.send('Page.enable', {}, sessionId)
  await cdp.send('Network.enable', {}, sessionId)

  // 2. 收集 Trace 事件
  const traceEvents = []
  cdp.on('Tracing.dataCollected', (params) => {
    traceEvents.push(...params.value)
  })

  // 3. 开始追踪 — 指定要采集的类别
  await cdp.send('Tracing.start', {
    categories: [
      'devtools.timeline',      // 渲染管线事件
      'v8.execute',             // V8 JS 执行
      'disabled-by-default-devtools.timeline',  // 详细时间线
      'blink.user_timing'       // performance.mark/measure
    ].join(','),
    bufferUsageReportingInterval: 1000
  }, sessionId)

  // 4. 导航到目标页面
  await cdp.send('Page.navigate', { url }, sessionId)
  await cdp.send('Page.loadEventFired', {}, sessionId)  // 等待加载完成

  // 5. 停止追踪
  const { traceEvents: completeEvents } = await cdp.send('Tracing.end', {}, sessionId)
  traceEvents.push(...(completeEvents || []))

  // 6. 保存为 JSON 文件
  const fs = await import('fs')
  fs.writeFileSync('trace-output.json', JSON.stringify(traceEvents))

  return traceEvents
}

3.2 采集 Core Web Vitals 指标

通过 CDP 的 Performance 域和 Runtime 域组合，可以精确采集 Core Web Vitals：

// web-vitals-collector.mjs — 用 CDP 采集 Core Web Vitals
// 比 web-vitals 库更精确，因为直接从浏览器内部获取

async function collectWebVitals(cdp, sessionId, url) {
  await cdp.send('Performance.enable', {}, sessionId)
  await cdp.send('Page.enable', {}, sessionId)

  // 注入 PerformanceObserver 来采集 LCP 和 CLS
  await cdp.send('Runtime.evaluate', {
    expression: `
      window.__vitals = {};
      
      // LCP — Largest Contentful Paint
      new PerformanceObserver((list) => {
        const entries = list.getEntries();
        window.__vitals.lcp = entries[entries.length - 1].startTime;
      }).observe({ type: 'largest-contentful-paint', buffered: true });

      // CLS — Cumulative Layout Shift
      let clsValue = 0;
      new PerformanceObserver((list) => {
        for (const entry of list.getEntries()) {
          if (!entry.hadRecentInput) clsValue += entry.value;
        }
        window.__vitals.cls = clsValue;
      }).observe({ type: 'layout-shift', buffered: true });

      // FCP — First Contentful Paint
      new PerformanceObserver((list) => {
        window.__vitals.fcp = list.getEntries()[0].startTime;
      }).observe({ type: 'paint', buffered: true });
    `,
    returnByValue: true
  }, sessionId)

  // 导航并等待加载
  await cdp.send('Page.navigate', { url }, sessionId)
  await new Promise(resolve => setTimeout(resolve, 5000))  // 等待 5 秒采集数据

  // 读取采集结果
  const { result } = await cdp.send('Runtime.evaluate', {
    expression: 'JSON.stringify(window.__vitals)',
    returnByValue: true
  }, sessionId)

  const metrics = JSON.parse(result.value)

  // 从 Performance.getMetrics 获取更多指标
  const { metrics: perfMetrics } = await cdp.send('Performance.getMetrics', {}, sessionId)
  const ttfb = perfMetrics.find(m => m.name === 'ResponseEnd')?.value -
               perfMetrics.find(m => m.name === 'RequestStart')?.value

  return {
    LCP: metrics.lcp?.toFixed(1) + ' ms',
    CLS: metrics.cls?.toFixed(4),
    FCP: metrics.fcp?.toFixed(1) + ' ms',
    TTFB: ttfb?.toFixed(1) + ' ms'
  }
}

// 使用示例
const vitals = await collectWebVitals(cdp, sessionId, 'https://example.com')
console.table(vitals)
// ┌─────────┬──────────┐
// │ (index) │  值      │
// ├─────────┼──────────┤
// │ LCP     │ '820.5 ms'│
// │ CLS     │ '0.0012' │
// │ FCP     │ '450.3 ms'│
// │ TTFB    │ '120.8 ms'│
// └─────────┴──────────┘

⚠️ 警告： CDP 的 Performance.getMetrics 返回的是 Chrome 内部指标（如 JSHeapUsedSize、Documents 等），与 Core Web Vitals 不完全对应。要采集真正的 CWV 指标，需要注入 PerformanceObserver 代码到页面中执行，如上面的示例所示。

🔧 四、实战场景三：内存分析与泄漏检测

4.1 堆快照分析

CDP 的 HeapProfiler 域可以生成 V8 堆快照（Heap Snapshot），这是定位内存泄漏的终极武器：

// memory-analyzer.mjs — 用 CDP 堆快照检测内存泄漏
// 对比两个时间点的堆快照，找出增长的对象

async function detectMemoryLeaks(cdp, sessionId, actions) {
  await cdp.send('HeapProfiler.enable', {}, sessionId)

  // 1. 基线快照：执行操作前
  const snapshot1 = await takeHeapSnapshot(cdp, sessionId)

  // 2. 执行待测试的操作（多次）
  for (let i = 0; i < 100; i++) {
    await actions()
  }

  // 3. 强制 GC
  await cdp.send('HeapProfiler.collectGarbage', {}, sessionId)

  // 4. 对比快照：执行操作后
  const snapshot2 = await takeHeapSnapshot(cdp, sessionId)

  // 5. 分析差异
  const diff = analyzeSnapshotDiff(snapshot1, snapshot2)
  return diff
}

async function takeHeapSnapshot(cdp, sessionId) {
  const chunks = []
  
  // 收集快照数据流
  cdp.on('HeapProfiler.addHeapSnapshotChunk', (params) => {
    chunks.push(params.chunk)
  })

  await cdp.send('HeapProfiler.takeHeapSnapshot', {
    reportProgress: false,
    treatGlobalObjectsAsRoots: true
  }, sessionId)

  return JSON.parse(chunks.join(''))
}

function analyzeSnapshotDiff(before, after) {
  // 统计各类型的节点数量变化
  const beforeNodes = countByType(before)
  const afterNodes = countByType(after)

  const diff = []
  for (const [type, count] of Object.entries(afterNodes)) {
    const prevCount = beforeNodes[type] || 0
    if (count > prevCount * 1.5) {  // 增长超过 50%
      diff.push({
        type,
        before: prevCount,
        after: count,
        growth: `+${((count / prevCount - 1) * 100).toFixed(1)}%`
      })
    }
  }

  return diff.sort((a, b) => b.after - a.after)
}

function countByType(snapshot) {
  const counts = {}
  // 堆快照的 nodes 数组中，每个节点有 type 字段
  for (const node of snapshot.nodes || []) {
    const type = snapshot.strings?.[node.type] || 'unknown'
    counts[type] = (counts[type] || 0) + 1
  }
  return counts
}

4.2 内存使用趋势监控

对于长时间运行的应用，可以用 CDP 定期采集内存指标，绘制趋势图：

// memory-monitor.mjs — 定期采集内存指标
// 用于检测缓慢的内存泄漏

async function monitorMemoryTrend(cdp, sessionId, durationMs = 60000) {
  await cdp.send('Performance.enable', {}, sessionId)
  
  const samples = []
  const interval = 1000  // 每秒采样一次
  const startTime = Date.now()

  while (Date.now() - startTime < durationMs) {
    const { metrics } = await cdp.send('Performance.getMetrics', {}, sessionId)
    
    const jsHeap = metrics.find(m => m.name === 'JSHeapUsedSize')?.value || 0
    const totalHeap = metrics.find(m => m.name === 'JSHeapTotalSize')?.value || 0
    const documents = metrics.find(m => m.name === 'Documents')?.value || 0
    const domNodes = metrics.find(m => m.name === 'Nodes')?.value || 0
    const listeners = metrics.find(m => m.name === 'JSEventListeners')?.value || 0

    samples.push({
      timestamp: Date.now() - startTime,
      jsHeapMB: (jsHeap / 1024 / 1024).toFixed(2),
      totalHeapMB: (totalHeap / 1024 / 1024).toFixed(2),
      documents,
      domNodes,
      jsEventListeners: listeners
    })

    await new Promise(r => setTimeout(r, interval))
  }

  // 检测内存增长趋势
  const first = samples[0]
  const last = samples[samples.length - 1]
  const heapGrowth = ((last.jsHeapMB - first.jsHeapMB) / first.jsHeapMB * 100).toFixed(1)

  console.log(`📊 内存监控报告（${durationMs / 1000} 秒）`)
  console.log(`   JS 堆内存: ${first.jsHeapMB}MB → ${last.jsHeapMB}MB (${heapGrowth > 0 ? '+' : ''}${heapGrowth}%)`)
  console.log(`   DOM 节点数: ${first.domNodes} → ${last.domNodes}`)
  console.log(`   事件监听器: ${first.jsEventListeners} → ${last.jsEventListeners}`)

  if (parseFloat(heapGrowth) > 20) {
    console.warn('⚠️ 内存增长超过 20%，可能存在内存泄漏！')
  }

  return samples
}

💡 五、最佳实践与避坑指南

5.1 CDP 与 Puppeteer 的正确组合

大多数项目不需要「纯 CDP」或「纯 Puppeteer」，而是两者的组合——用 Puppeteer 处理常规操作，用 CDP 处理 Puppeteer 不支持的高级功能：

// hybrid-approach.mjs — Puppeteer + CDP 混合使用
// 90% 用 Puppeteer API，10% 用 CDP 高级能力

import puppeteer from 'puppeteer'

const browser = await puppeteer.launch({ headless: 'new' })
const page = await browser.newPage()

// 常规操作用 Puppeteer API
await page.goto('https://example.com')
await page.type('#search', 'CDP Protocol')
await page.click('#submit')

// 高级操作用 CDP —— 通过 page.createCDPSession()
const client = await page.createCDPSession()

// 示例 1：模拟弱网环境
await client.send('Network.emulateNetworkConditions', {
  offline: false,
  downloadThroughput: (500 * 1024) / 8,   // 500 Kbps
  uploadThroughput: (250 * 1024) / 8,      // 250 Kbps
  latency: 300                              // 300ms 延迟
})

// 示例 2：打印 PDF（Puppeteer 有，但 CDP 选项更丰富）
const { data } = await client.send('PrintToPDF', {
  printBackground: true,
  preferCSSPageSize: true,
  scale: 0.8,
  paperWidth: 8.27,    // A4 宽度（英寸）
  paperHeight: 11.69
})

// 示例 3：拦截并修改响应头
await client.send('Network.setExtraHTTPHeaders', {
  headers: {
    'X-Custom-Header': 'cdp-test',
    'Accept-Language': 'zh-CN,zh;q=0.9'
  }
})

5.2 常见陷阱

5.3 生产级 CDP 客户端封装

// production-cdp.mjs — 带超时、重试、事件清理的 CDP 客户端

class ProductionCDP {
  #client = null
  #sessionId = null
  #cleanupFns = []

  static async create(wsUrl, targetId, timeout = 10000) {
    const instance = new ProductionCDP()
    instance.#client = new CDPClient()
    
    await Promise.race([
      instance.#client.connect(wsUrl),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('CDP 连接超时')), timeout)
      )
    ])

    const { sessionId } = await instance.#client.send(
      'Target.attachToTarget',
      { targetId, flatten: true }
    )
    instance.#sessionId = sessionId

    return instance
  }

  // 带超时的命令发送
  async send(method, params = {}, timeout = 30000) {
    return Promise.race([
      this.#client.send(method, params, this.#sessionId),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error(`CDP 命令超时: ${method}`)), timeout)
      )
    ])
  }

  // 事件监听（自动注册清理函数）
  on(event, handler) {
    this.#client.on(event, handler)
    this.#cleanupFns.push(() => {
      // 移除监听器的逻辑
    })
  }

  // 优雅关闭
  async dispose() {
    for (const fn of this.#cleanupFns) fn()
    this.#cleanupFns = []
    this.#client?.close()
  }
}

📊 六、CDP 能力全景对比

⚡ 关键结论： 对于 90% 的自动化测试和爬虫项目，Playwright 是最佳选择——它支持多浏览器、API 设计优秀、社区活跃。对于需要深度性能分析、内存调试、或自定义协议扩展的场景，直接使用 CDP 是唯一正确方案。两者不是替代关系，而是互补。

🎯 总结

CDP 是浏览器自动化的「汇编语言」——你不会用它写日常代码，但理解它能让你在关键时刻做出正确的技术决策。以下是学习 CDP 的建议路径：

1. 第一步：用 chrome://inspect 远程调试一个页面，熟悉 CDP 的命令面板
2. 第二步：在 Puppeteer 中用 page.createCDPSession() 尝试几个高级命令
3. 第三步：为你的项目构建一个定制化的 CDP 采集工具（如性能监控、错误追踪）

相关工具推荐：

• 🔧 Puppeteer — 最流行的 Chrome 自动化库，底层就是 CDP
• 🔧 Playwright — 多浏览器自动化框架，支持 CDP 扩展
• 🔧 chrome-remote-interface — Node.js CDP 客户端库
• 🔧 CDP 官方文档 — 最权威的协议参考
• 🔧 jsjson.com JSON 格式化工具 — 格式化 CDP 返回的 JSON 数据