chrome-cdp工作原理解析：如何通过WebSocket与Chrome DevTools协议通信

chrome-cdp工作原理解析：如何通过WebSocket与Chrome DevTools协议通信

【免费下载链接】chrome-cdp-skillGive your AI agent access to your live Chrome session — works out of the box, connects to tabs you already have open项目地址: https://gitcode.com/gh_mirrors/ch/chrome-cdp-skill

chrome-cdp是一个轻量级Chrome DevTools Protocol (CDP)工具，它能让AI代理直接访问您的实时Chrome会话，无需额外配置即可连接到已打开的标签页。本文将深入解析其工作原理，特别是如何通过WebSocket实现与Chrome DevTools协议的通信。

什么是Chrome DevTools协议（CDP）？

Chrome DevTools协议是一套强大的API，允许开发者与Chrome浏览器进行交互，实现调试、性能分析、页面控制等功能。传统上，这需要通过Chrome DevTools界面或复杂的库（如Puppeteer）来使用。而chrome-cdp则提供了一种更轻量级的方式，直接通过WebSocket与CDP通信，无需额外依赖。

chrome-cdp的核心优势

chrome-cdp的设计理念是"轻量级"和"即开即用"，主要优势包括：

• 无依赖：不需要安装Puppeteer等大型库，使用Node.js内置的WebSocket模块
• 高效连接：直接与已打开的Chrome标签页建立连接，支持100+标签页
• 持久会话：每个标签页通过守护进程（daemon）保持连接，避免重复授权
• 简单易用：提供直观的命令行接口，如snap获取页面结构、shot截图、eval执行JavaScript等

WebSocket通信的工作流程

chrome-cdp通过WebSocket与Chrome DevTools协议通信的过程可以分为四个关键步骤：

1. 发现Chrome调试接口

首先，chrome-cdp需要找到Chrome的远程调试接口。它会搜索多个可能的位置来查找DevToolsActivePort文件，该文件包含了调试端口信息：

// 搜索可能的DevToolsActivePort位置 const candidates = [ process.env.CDP_PORT_FILE, // macOS路径 ...macBrowsers.flatMap(b => [ resolve(home, 'Library/Application Support', b, 'DevToolsActivePort'), ]), // Linux路径 ...linuxBrowsers.flatMap(b => [ resolve(home, '.config', b, 'DevToolsActivePort'), ]), // Windows路径 ...(IS_WINDOWS ? ['Google/Chrome', 'BraveSoftware/Brave-Browser'].flatMap(b => [ resolve(base, b, 'User Data/DevToolsActivePort'), ]) : []), ];

找到端口文件后，它会读取文件内容获取WebSocket URL：ws://127.0.0.1:<port>/<devtoolsFrontendUrl>

2. 建立WebSocket连接

chrome-cdp创建了一个CDP类来管理WebSocket连接，实现了协议的核心通信功能：

class CDP { #ws; #id = 0; #pending = new Map(); #eventHandlers = new Map(); async connect(wsUrl) { return new Promise((res, rej) => { this.#ws = new WebSocket(wsUrl); this.#ws.onopen = () => res(); this.#ws.onerror = (e) => rej(new Error('WebSocket error: ' + e.message)); this.#ws.onmessage = (ev) => { const msg = JSON.parse(ev.data); // 处理响应和事件... }; }); } // 发送CDP命令 send(method, params = {}, sessionId) { const id = ++this.#id; return new Promise((resolve, reject) => { this.#pending.set(id, { resolve, reject }); const msg = { id, method, params }; if (sessionId) msg.sessionId = sessionId; this.#ws.send(JSON.stringify(msg)); // 超时处理... }); } }

3. 标签页会话管理

chrome-cdp采用了"每个标签页一个守护进程"的架构。当您第一次访问某个标签页时，会启动一个后台守护进程：

// 启动标签页守护进程 async function getOrStartTabDaemon(targetId) { const sp = sockPath(targetId); // 尝试连接现有守护进程 try { return await connectToSocket(sp); } catch {} // 启动新的守护进程 const child = spawn(process.execPath, [process.argv[1], '_daemon', targetId], { detached: true, stdio: 'ignore', }); child.unref(); // 等待守护进程就绪 for (let i = 0; i < DAEMON_CONNECT_RETRIES; i++) { await sleep(DAEMON_CONNECT_DELAY); try { return await connectToSocket(sp); } catch {} } throw new Error('Daemon failed to start — did you click Allow in Chrome?'); }

这个守护进程会处理所有针对该标签页的命令，并在闲置20分钟后自动退出，既保证了操作的连续性，又不会浪费系统资源。

4. 执行CDP命令

一旦建立连接，chrome-cdp就可以发送各种CDP命令。例如，获取页面截图的实现：

async function shotStr(cdp, sid, filePath, targetId) { // 获取设备像素比(DPR) let dpr = 1; try { const metrics = await cdp.send('Page.getLayoutMetrics', {}, sid); dpr = metrics.visualViewport?.clientWidth / metrics.cssVisualViewport?.clientWidth || 1; } catch {} // 发送截图命令 const { data } = await cdp.send('Page.captureScreenshot', { format: 'png' }, sid); const out = filePath || resolve(RUNTIME_DIR, `screenshot-${targetId.slice(0, 8)}.png`); writeFileSync(out, Buffer.from(data, 'base64')); return `Screenshot saved. Device pixel ratio (DPR): ${dpr}`; }

实际应用示例

chrome-cdp提供了丰富的命令行接口，让您可以轻松与Chrome交互：

1. 列出所有打开的页面

scripts/cdp.mjs list

2. 对指定页面截图

scripts/cdp.mjs shot <target> [file]

3. 在页面上执行JavaScript

scripts/cdp.mjs eval <target> "document.title"

4. 点击页面元素

scripts/cdp.mjs click <target> "button.submit"

坐标系统转换

使用截图和点击功能时，需要注意坐标系统的转换。Chrome的截图使用设备像素，而CDP的输入事件使用CSS像素：

CSS像素 = 截图图像像素 / DPR（设备像素比）

例如，在DPR=2的Retina屏幕上，截图中(200, 300)的像素点对应CSS坐标(100, 150)，需要使用clickxy命令时应传入后者。

结语

chrome-cdp通过WebSocket直接与Chrome DevTools协议通信，提供了一种轻量级、高效的方式来控制和调试Chrome浏览器。其设计理念使得AI代理能够轻松访问和操作浏览器内容，为自动化测试、网页数据提取、无障碍测试等场景提供了强大支持。

无论是开发者还是AI代理，都可以通过简单的命令行接口，利用Chrome DevTools协议的全部能力，而无需深入了解协议细节。这正是chrome-cdp的价值所在：简化复杂技术，让强大功能触手可及。

要开始使用chrome-cdp，只需克隆仓库并按照说明启用Chrome的远程调试功能：

git clone https://gitcode.com/gh_mirrors/ch/chrome-cdp-skill

然后您就可以立即体验这个强大工具带来的便利，探索Chrome DevTools协议的无限可能。

【免费下载链接】chrome-cdp-skillGive your AI agent access to your live Chrome session — works out of the box, connects to tabs you already have open项目地址: https://gitcode.com/gh_mirrors/ch/chrome-cdp-skill