协议快照:
devtools-protocol 0.0.1748923本文是 CDP 系列第 3 篇,聚焦
Network与Fetch两个域。
先附上官方文档
你想做三类很常见的事:
- 记录页面加载过程中的请求和响应;
- 在请求发出前改 URL、改 header、改 body,或者直接让某个请求失败;
- 在响应返回后改状态码、改 header,甚至换掉响应体。
Network 负责观察和查询,Fetch 负责暂停与控制。两者经常一起使用,但职责不同:Network 是观察者,Fetch 是拦截器。
两个域的职责边界
Network 管什么
- 请求/响应事件流:requestWillBeSent、responseReceived、loadingFinished、loadingFailed
- 请求体、响应体查询
- Cookie 读写与删除
- 缓存开关、Service Worker bypass
- 额外 HTTP header
- WebSocket / EventSource / WebTransport 事件
- 网络条件仿真的历史入口(现已 redirect 到 Emulation)
- Reporting API、Direct Socket 等实验能力
Network 不会暂停请求。它可以告诉你请求发生了什么,也可以读取 body,但不能在请求中间要求浏览器等待你的决定。
Fetch 管什么
- 按 URL pattern / resourceType / requestStage 暂停请求
- 对暂停的请求执行 continue、fail、fulfill
- 修改请求 URL、method、postData、headers
- 修改响应状态码和 headers
- 处理 HTTP 认证挑战
- 获取被拦截响应的 body 或转成 IO stream
Fetch 的注释写得很清楚:它是让客户端替代浏览器网络层的域。请求一旦被暂停,客户端必须调用 continueRequest、failRequest、fulfillRequest 之一,或对认证场景调用 continueWithAuth,否则请求会一直等待。
当前状态
| 域 | 域级状态 | 命令 | 事件 | 稳定命令 | 稳定事件 |
|---|---|---|---|---|---|
| Network | 稳定 | 35 | 43 | 14 | 17 |
| Fetch | 稳定 | 9 | 2 | 8 | 2 |
Fetch 的 continueResponse 是实验命令,其余核心命令稳定。Network 的核心监听命令和事件大多稳定,但 extra info、Direct Socket、Reporting API、resource streaming 等大量能力是实验项。
Network 核心命令
Network.enable / Network.disable
开启网络事件流。没有 enable,大部分 Network 事件不会发送。
json
{
"id": 1,
"method": "Network.enable",
"params": {
"maxPostDataSize": 65536
}
}
常用参数:
maxPostDataSize:requestWillBeSent 中保留的最大 post body 长度maxTotalBufferSize/maxResourceBufferSize:实验参数,控制 payload 缓冲reportDirectSocketTraffic:实验参数enableDurableMessages:实验参数,已建议改用Network.configureDurableMessages
Network.getResponseBody
根据 requestId 读取响应体。
json
{
"id": 2,
"method": "Network.getResponseBody",
"params": { "requestId": "..." }
}
返回:
body:响应体字符串base64Encoded:是否需要按 base64 解码
注意:必须在响应可用且数据仍被保留时调用。跨进程导航、缓冲区回收、Network.disable 都可能让 body 不再可读。
Network.getRequestPostData
读取请求 post body,返回 postData 和 base64Encoded。没有 body 时会报错。是否包含数据受 Network.enable.maxPostDataSize 影响。
Network.getCookies / Network.setCookies / Network.setCookie
Cookie 操作核心。
getCookies 可传 urls,不传时默认当前页面及其子 frame 相关 cookie。
setCookies 接受 CookieParam[],适合批量写入。
setCookie 是单个 cookie 写入,支持:
name/valueurl/domain/pathsecure/httpOnlysameSiteexpires- 实验参数:
priority、sourceScheme、sourcePort、partitionKey
Network.getAllCookies 已废弃,PDL 建议改用 Storage.getCookies。
Network.deleteCookies / clearBrowserCookies / clearBrowserCache
deleteCookies:按 name + url/domain/path 删除clearBrowserCookies:清空浏览器 cookieclearBrowserCache:清空浏览器缓存
这些都是有副作用的命令,自动化测试里要谨慎使用,避免影响共享 profile。
Network.setExtraHTTPHeaders
给当前页面后续请求统一附加 HTTP header。
json
{
"method": "Network.setExtraHTTPHeaders",
"params": {
"headers": {
"x-debug-client": "cdp-example"
}
}
}
它影响的是 DevTools session 管理的请求,不等价于修改浏览器全局网络栈。
Network.setCacheDisabled / Network.setBypassServiceWorker
setCacheDisabled(true):请求不使用缓存setBypassServiceWorker(true):绕过 Service Worker,直接走网络
这两个命令在做网络测试、缓存验证、Service Worker 排查时很常用。
Network.setBlockedURLs
实验命令,用 URLPattern 阻止请求加载。新版 urlPatterns 使用 BlockPattern,支持 block: false 做例外;旧 urls 字符串数组已废弃。
Network.emulateNetworkConditions
已废弃,redirect 到 Emulation。新代码应使用 Network.emulateNetworkConditions 对应的 Emulation 域命令,而不是旧入口。
Network 核心事件
一个典型请求生命周期:
text
requestWillBeSent
-> responseReceived
-> dataReceived (可多次)
-> loadingFinished
失败时:
text
requestWillBeSent
-> loadingFailed
Network.requestWillBeSent
请求即将发出。关键字段:
requestIdloaderIdrequest:URL、method、headers、postData 等timestamp/wallTimeinitiator:请求来源redirectResponse:如果这是重定向后的新请求,带上一跳响应frameIdtype:Document、Script、XHR、Fetch 等
这是建立请求索引表的起点。
Network.responseReceived
响应头可用。关键字段:
requestIdtyperesponse:url、status、statusText、headers、mimeType、protocol、remoteIPAddress、timing 等hasExtraInfo:实验字段,表示是否伴随 extra info 事件
注意:这个事件只说明响应头到了,不代表 body 已完整接收。
Network.dataReceived
收到数据块,可多次触发。字段包括 dataLength、encodedDataLength。实验版本可携带原始 data。
Network.loadingFinished
请求完成,带总 encodedDataLength。这是调用 getResponseBody 的常用时机。
Network.loadingFailed
请求失败,字段包括:
errorTextcanceledblockedReasoncorsErrorStatus
排查 CORS、blocked request、取消加载时优先看这个事件。
Network.requestServedFromCache
请求命中缓存。判断"请求是否真的走网络"时要结合这个事件,不能只看 responseReceived。
WebSocket 事件
webSocketCreatedwebSocketWillSendHandshakeRequestwebSocketHandshakeResponseReceivedwebSocketFrameSent/webSocketFrameReceivedwebSocketFrameErrorwebSocketClosed
这组事件可以完整还原 WebSocket 生命周期,但它们不是 Fetch 暂停点;修改 WebSocket 帧的能力不属于这组稳定事件。
Fetch 核心命令
Fetch.enable
开启拦截,并声明拦截规则。
json
{
"id": 10,
"method": "Fetch.enable",
"params": {
"patterns": [
{
"urlPattern": "*://example.com/api/*",
"requestStage": "Request"
}
],
"handleAuthRequests": false
}
}
RequestPattern 字段:
urlPattern:支持*和?通配;省略等价于"*"resourceType:只拦截指定资源类型requestStage:Request或Response,默认 Request
Request 阶段在请求发出前暂停;Response 阶段在响应头到达后、响应体接收前暂停。
Fetch.requestPaused 事件
命中规则时触发,请求暂停。判断阶段的方法:
- 有
responseStatusCode/responseErrorReason/responseHeaders:Response 阶段 - 没有:Request 阶段
关键字段:
requestId:Fetch 侧请求 IDrequest:请求详情frameIdresourceTypenetworkId:如果对应 Network 事件,可与Network.requestWillBeSent.requestId关联redirectedRequestId:实验字段,重定向来源
Fetch.continueRequest
放行请求,可选择性修改参数:
urlmethodpostDataheadersinterceptResponse:实验参数,同时开启响应拦截
注意注释里的限制:header override 不会延续到后续 redirect hop。重定向产生新请求时,需要再次处理新的 paused request。
Fetch.failRequest
让请求失败,errorReason 使用 Network.ErrorReason,例如 Aborted、TimedOut、ConnectionRefused、BlockedByClient。
常用于屏蔽资源或模拟失败。
Fetch.fulfillRequest
直接给请求提供响应,不再访问网络。
参数:
responseCoderesponseHeadersbinaryResponseHeadersbodyresponsePhrase
如果省略 body:
- Response 阶段:使用原始响应体
- Request 阶段:使用空 body
body 是 binary 类型。协议 JSON 里 binary 字段按 base64 字符串传输,这是直接 CDP 和 Puppeteer 封装最容易踩差异的地方。
Fetch.continueResponse
实验命令。只修改响应状态码/headers 后继续加载,不替换 body。
规则是:如果改 responseCode 或 headers,必须同时提供完整 responseCode 和 headers。
Fetch.continueWithAuth
配合 Fetch.authRequired 事件处理 401/407 认证。AuthChallengeResponse.response 可选:
DefaultCancelAuthProvideCredentials
选择 ProvideCredentials 时提供 username/password。
Fetch.getResponseBody / Fetch.takeResponseBodyAsStream
getResponseBody:读取 Response 阶段被暂停请求的响应体takeResponseBodyAsStream:转成IO.StreamHandle,适合大响应
注释明确说明两者互斥。转成 stream 后,这个请求不能再原样 continue,需要取消或提供响应体。
最小示例:观察请求
javascript
function send(ws, method, params = {}) {
ws.send(JSON.stringify({ id: (send.id = (send.id ?? 0) + 1), method, params }));
}
const requests = new Map();
send(ws, "Network.enable", { maxPostDataSize: 65536 });
ws.on("message", (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.method === "Network.requestWillBeSent") {
const { requestId, request, type } = msg.params;
requests.set(requestId, {
url: request.url,
method: request.method,
type,
status: undefined,
});
}
if (msg.method === "Network.responseReceived") {
const item = requests.get(msg.params.requestId);
if (item) item.status = msg.params.response.status;
}
if (msg.method === "Network.loadingFinished") {
const id = msg.params.requestId;
const item = requests.get(id);
if (item) console.log(item.method, item.status, item.url);
}
});
这段代码只做观察,不改变请求。
最小示例:拦截并 mock 响应
javascript
send(ws, "Fetch.enable", {
patterns: [
{
urlPattern: "https://example.com/api/user",
requestStage: "Request",
},
],
});
ws.on("message", (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.method !== "Fetch.requestPaused") return;
const { requestId, request } = msg.params;
if (request.url === "https://example.com/api/user") {
send(ws, "Fetch.fulfillRequest", {
requestId,
responseCode: 200,
responseHeaders: [
{ name: "content-type", value: "application/json" },
],
body: Buffer.from(JSON.stringify({ id: 1, name: "cdp" })).toString("base64"),
});
return;
}
send(ws, "Fetch.continueRequest", { requestId });
});
关键点:
body用 base64 表示 binary 字段- 每个 paused request 都必须有终局动作
- 未命中细条件时也要
continueRequest,否则页面会挂起
与其他域的协作
Page:loaderId、frameId、导航时序Runtime:请求 initiator 的调用栈、页面脚本上下文IO:大响应体转 streamEmulation:离线、延迟、吞吐、连接类型等网络条件仿真Security:证书错误、混合内容、安全状态Storage:新代码中的全量 cookie 查询方向
常见坑
只开 Network,却想做拦截
Network 只能观察。要暂停和修改请求,必须开 Fetch.enable 并处理 requestPaused。
paused request 没有终局动作
每个 Fetch.requestPaused 都必须以 continueRequest、failRequest、fulfillRequest 之一结束;auth 场景则是 continueWithAuth。漏掉一个请求,页面就可能一直等待。
以为 requestId 完全等价
Network 的 requestId 和 Fetch 的 requestId 不是在所有场景都天然等价。Fetch 事件提供 networkId 时,应使用它关联 Network 请求。
在 responseReceived 就读 body
responseReceived 只表示响应头可用。读 body 通常要等 loadingFinished,或者在 Fetch Response 阶段处理。
忽略缓存
命中缓存的请求也可能有事件,但网络行为不同。要看 requestServedFromCache,并按需 setCacheDisabled(true)。
忽略重定向链
重定向会产生新的 requestWillBeSent,并在 redirectResponse 中带上一跳响应。Fetch 的 header override 不会自动延续到 redirect 后续请求。
使用废弃命令
Network.getAllCookies、Network.emulateNetworkConditions、Network.setUserAgentOverride 等入口已经废弃或 redirect。新代码应改用 Storage、Emulation 对应命令。
稳定状态速查
| 能力 | 状态 |
|---|---|
| Network.enable / disable | 稳定 |
| Network.getResponseBody / getRequestPostData | 稳定 |
| Network.getCookies / setCookies / setCookie / deleteCookies | 稳定;部分 cookie 属性实验 |
| Network.setExtraHTTPHeaders / setCacheDisabled | 稳定 |
| Network.setBypassServiceWorker | 稳定 |
| Network.setBlockedURLs | 实验 |
| Network.streamResourceContent | 实验 |
| Network request/response 基础事件 | 大多稳定 |
| requestWillBeSentExtraInfo / responseReceivedExtraInfo | 实验 |
| WebSocket 事件 | 稳定 |
| WebTransport / Direct Socket 事件 | 实验 |
| Fetch.enable / disable | 稳定 |
| Fetch.continueRequest / failRequest / fulfillRequest | 稳定 |
| Fetch.continueWithAuth | 稳定 |
| Fetch.getResponseBody / takeResponseBodyAsStream | 稳定 |
| Fetch.continueResponse | 实验 |
| Fetch requestPaused / authRequired | 稳定事件 |
下一篇
下一篇进入 DOM 与 CSS:如何查询节点、修改属性、读取计算样式与布局信息,以及为什么 CSS 域虽然功能强大,但整域仍是 experimental。