CDP Session 就是 Playwright 打开的一扇“后门”——在保持高层 API 优雅的同时让你能直达 CDP 协议层。

二、CDPSession 的创建方式与常见痛点方法

Playwright 提供两种方式获取 CDP Session，下面用代码演示并说明常见痛点：

. 页面级 Session— 解决“无法监控单页请求”的痛点。

. 浏览器级连接— 对 “复用已登录浏览器” 场景的常用方法。

const browser = await chromium.connectOverCDP;// 获取已有页面的 CDP Session
const contexts = browser.contexts;const page = contexts.pages;const cdp = await page.context.newCDPSession;await cdp.send;// 开启网络监控
// ...后续逻辑... 

三、CDPSession 主要 API 与典型痛点对照表

CDPSession 对象仅包含三大方法 + 两个事件模式，使用起来非常简洁。

┌──────────────────────────────────────────┐
│ CDPSession │
│ │
│ Methods: │
│ send → Promise|
│ detach → Promise|
│ │
│ Events: │
│ on │
│ off │
│ │
│ Lifecycle: │
│ 'disconnected' event │
└──────────────────────────────────────────┘

`send` — 发起 CDP 命令 — 用来解决 “想要执行 DevTools 协议但没有对应 Playwright API” 的痛点。

const result = await cdp.send('Runtime.evaluate'。{
expression: 'document.title',returnByValue: true,});console.log，// "Example Domain"

`on` — 监听 CDP 事件 — 用来解决 “想要实时监听网络/控制台/渲染事件但缺乏灵活性” 的痛点。怎么说呢，

await cdp.send;cdp.on('Network.requestWillBeSent',params => {
console.log;})，cdp.on('Network.responseReceived',params => {
console.log;})，

`detach` — 手动断开 Session — 用来解决 “Session 长期占用资源导致内存泄漏” 的痛点。

await cdp.detach;// 后续 send 将抛出错误提示 Session 已断开 

四、实战场景：让 Playwright 超越极限，直接掌握底层细节！

. 获取完整响应头——解决“headers 缺失”的痛点。

const cdp = await page.context.newCDPSession;await cdp.send;const responseHeaders = new Map;cdp.on => {
responseHeaders.set;})，await page.goto;for {
console.log;}

. 性能 Trace——解决“性能分析不够细粒度”的痛点。怎么说呢，

const cdp = await page.context.newCDPSession;await cdp.send('Tracing.start',{
traceConfig: {
includedCategories:,bufferUsageReportingIntervalMs: null。transferMode:'ReturnAsStream',recordMode:'recordUntilFull',disableSampling:true,recordMode:'recordUntilFull'
},});await page.goto;await page.click;await cdp.send;cdp.on => {
console.log;})，不过，

. JS 覆盖率——解决“代码覆盖率工具集成困难”的痛点。

const cdp = await page.context.newCDPSession;await cdp.send;await cdp.send;await page.goto;// ... 使用者操作 ...
const coverage = await cdp.send;for{
console.log;for{
console.log;}
}
await cdp.send;}

. 地理位置欺骗——精细化模拟不同地区使用者体验，解决“地理限制测试不方便”的痛点。

const cdp = await page.context.newCDPSession;await cdp.send("Emulation.setGeolocationOverride"。{
latitude:35.6895,longitude:-139.6917,accuracy:1000,});await page.goto;说起来，console.log;说起来，}

. 拦截并修改响应——解决“无法更改第三方接口返回值”的痛点。

const cdp= await page.context.newCDPSession;await cdp.send;不过，await cdp.send;cdp.on=>{
const newUrl=request.url.replace;
// 重写URL
await cdp.send;})，}

. SSL 证书错误处理——让自动化脚本忽略自签名或失效证书，解决 “HTTPS 测试中证书错误导致失败”的痛点。

const cdp= await page.context.newCDPSession;await cdp.send;await cdp.send;cdp.on=>{
console.log;
// 忽略错误继续加载
await cdp.send;
})，其实，}

五、多 Session 并行管理：同一页面可创建多个独立 CDPs —— 减少冲突、提高可观测性！

同一个页面可以拥有多个互不干扰的 CDP Session，例如同时监控网络和控制台日志：

const sessionNet = await page.context.newCDPSession;sessionNet.on;})，const sessionConsole = await page.context.newCDPSession;sessionConsole.on;})，// 两个 Session 独立，各自拥有自己的 WebSocket 通道。// 可以根据业务需求开启不同类型协议。

🧩 Caveat: 每个 `Session` 都会打开一个新的 WebSocket；在高并发场景下请注意资源消耗。说起来，🛠️ TIPS: 如果只需一次性抓包。可在 `one‑time session` 中使用 `detach` 来释放资源。🧪 TUTORIAL: Performance Trace Demo** **
📚 LATER: 查看完整可调用方法列表** **
✉️ 若遇到任何异常，请先确认是否为 Chrome 调试端口未开启或已被占用。💡 推荐阅读：Playwright 官方文档中的。@on,@detach 三大主要方法。📄 参考：https://playwright.dev/docs/api/class-cdpsession
🔗 更多实例请关注官方 GitHub 示例仓库。💬 如果你还有其他想了解的话题，请留言交流！✈️ 感谢阅读，希望这些示例能帮你快速把 Playwright 推到更高阶应用层面。---
## 六、connectOverCDP — 接管已有浏览器实例

当你已经启动了带调试端口的 Chrome，并希望在 Playwright 中复用它时只需一行代码就可以完成连接：


先启动 Chrome 并开启远程调试端口：`chrome --remote-debugging-port=9222`；如果是 Windows 环境请使用完整方法 `C:\Program Files\Google\Chrome\Application\chrome.exe` 等等；如果是 macOS/Linux 则可以直接 `google-chrome --remote-debugging-port=9222`；话说回来，这一步确保 Chrome 能接受外部 WebSocket 请求。

在你的脚本里使用 `chromium.connectOverCDP` 链接上去：
javascript const browser= await chromium.connectOverCDP;

拿到已有上下文与标签页后即可继续玩耍：
javascript const context=browser.contexts;老实说，const pages=context.pages;const targetPage=pages;

既可以走 Playwright 高层 API，也可以新建 `CDPSession`：
javascript const session=context.newCdpsession;

此时所有 Cookie / 登录态都保留，你无需重复登录即可进行自动化测试。


*典型场景*:


复用已登录的浏览器

操作已有标签页

与其他基于 DevTools Protocol 的工具共享同一实例。











---
## 七、Playwright vs Puppeteer 在 CDPv0 层面的区别



维度
Playwright
Puppeteer


Session 创建
#context.newCdpsession| | | | | | | | | | |
.?，?，.?.，?...















八、注意事项 & 陷阱

. 与 Playwright API 冲突可能导致请求卡住

javascript
// ❌ 不要同时两边做拦截，否则会冲突导致卡住！page.route，// Playwright 拦截方式；cpd.session，.send;其实，// 两者互相覆盖，最终请求可能永远挂起。// 原则：同一功能只选一种实现方式。其实，

. 在非 Chromium 浏览器上无法使用

javascript /* 报错信息 */
try{
const session=document.pageContext.newCdpsession
}catch{console.error} // "No such method …"


. 建议提前判断环境：

javascript if!=‘chromium’) throw Error


. 会话断开的安全处理

javascript const session=document.pageContext.newCdpsesion
session.on=>console.warn)
try{ /* 输入命令 */ }catch{if) {/* handle close */}}


. 时序问题 - 必须先启用协议再导航

javascript /* ❌ 错误 */
page.goto
session!.send

// ✅ 正确顺序：
session!.send
page.goto


. 性能成本 - 每个 Session 都是一个 WebSocket

scss /* 避免循环创建 */
for{
if{/* 每十个重置一次*/}else{
const sess=document.pageContext.newCdpsesion
}
}



九、架构全景图 & 理解其工作原理


'


使用者代码 → 高层API → Page → Frame → Locator …⇒ 实际执行时会在内部调用以下方法：


User : page.click → High‑Level Layer : Page object triggers internal logic.

High‑Level Layer : Calls Internal DevTools Agent via WebSocket,wrapped by Transport Layer.

Transport Layer : Chooses 娱乐ween Pipe for normal calls or WebSocket when using connectOverCDP.

WebSocket : Directly talks to Chrome DevTools Agent。which n executes requested command via Chrome DevTools Protocol.

Finally results flow back through same chain until reaching your script.


This diagram shows how a single call `) traverses from your code down to raw protocol and back again.


十、TypeScript 类型支持 & 如何获得完整定义

虽然 Playwright 内置了基本类型，但若想拥有更完整、更类型安全的协议定义，可以安装官方类型包：

bash npm install @types/chrome-devtools-protocol --save-dev
接下来就可以像下面这样声明：

ts import {type CDPMessage} from '@types/chrome-devtools-protocol';import {type CDPSession} from 'playwright';async function demo{
const resp:any=session.awaitSend<'Runtime.evaluate'>;按理说，// any 类型，需要自行断言结果结构...
}


若想获得更细粒度的方法签名。可以查看官方 TypeScript 声明文件中 @types/chrome-devtools-protocol.d.ts。



概念
一句话描述 |


`C D P S e s s i o n` ：Chrome DevTools Protocol 会话通道
→ 在跨浏览器抽象之上提供底层访问窗口 |
创建方式 `context.newCdpsesion` 或 `browser.connectOverC dp` |

主要方法 — `send`/`on`/`detach`— 发送命令 / 注册事件 / 手动关闭 |


多会话支持 — 同一页面可创建多个独立会话，不互相干扰 |


适配场景 — 当高层 API 无法满足需求时如抓包、Trace、覆盖率、伪造证书等 |


限制 — 仅 Chromium 支持；需避免与 Playwright 原生拦截混用 |


事件命名差异 — No domain prefix in Playwright events vs Puppeteer |
 









C D P S e s s i o n 是在 PlayWright 跨浏览器抽象之上的活板门。让你能够精准掌握 Chromium 内核内部行为，同时保持高级 API 的优雅体验。