《Chrome CDP 系列》网络监听与拦截:Network / Fetch

协议快照:devtools-protocol 0.0.1748923

本文是 CDP 系列第 3 篇,聚焦 Network 与 Fetch 两个域。


先附上官方文档

你想做三类很常见的事:

  1. 记录页面加载过程中的请求和响应;
  2. 在请求发出前改 URL、改 header、改 body,或者直接让某个请求失败;
  3. 在响应返回后改状态码、改 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 / value
  • url / domain / path
  • secure / httpOnly
  • sameSite
  • expires
  • 实验参数:priority、sourceScheme、sourcePort、partitionKey

Network.getAllCookies 已废弃,PDL 建议改用 Storage.getCookies。

Network.deleteCookies / clearBrowserCookies / clearBrowserCache

  • deleteCookies:按 name + url/domain/path 删除
  • clearBrowserCookies:清空浏览器 cookie
  • clearBrowserCache:清空浏览器缓存

这些都是有副作用的命令,自动化测试里要谨慎使用,避免影响共享 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

请求即将发出。关键字段:

  • requestId
  • loaderId
  • request:URL、method、headers、postData 等
  • timestamp / wallTime
  • initiator:请求来源
  • redirectResponse:如果这是重定向后的新请求,带上一跳响应
  • frameId
  • type:Document、Script、XHR、Fetch 等

这是建立请求索引表的起点。

Network.responseReceived

响应头可用。关键字段:

  • requestId
  • type
  • response:url、status、statusText、headers、mimeType、protocol、remoteIPAddress、timing 等
  • hasExtraInfo:实验字段,表示是否伴随 extra info 事件

注意:这个事件只说明响应头到了,不代表 body 已完整接收。

Network.dataReceived

收到数据块,可多次触发。字段包括 dataLength、encodedDataLength。实验版本可携带原始 data。

Network.loadingFinished

请求完成,带总 encodedDataLength。这是调用 getResponseBody 的常用时机。

Network.loadingFailed

请求失败,字段包括:

  • errorText
  • canceled
  • blockedReason
  • corsErrorStatus

排查 CORS、blocked request、取消加载时优先看这个事件。

Network.requestServedFromCache

请求命中缓存。判断"请求是否真的走网络"时要结合这个事件,不能只看 responseReceived。

WebSocket 事件

  • webSocketCreated
  • webSocketWillSendHandshakeRequest
  • webSocketHandshakeResponseReceived
  • webSocketFrameSent / webSocketFrameReceived
  • webSocketFrameError
  • webSocketClosed

这组事件可以完整还原 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 侧请求 ID
  • request:请求详情
  • frameId
  • resourceType
  • networkId:如果对应 Network 事件,可与 Network.requestWillBeSent.requestId 关联
  • redirectedRequestId:实验字段,重定向来源

Fetch.continueRequest

放行请求,可选择性修改参数:

  • url
  • method
  • postData
  • headers
  • interceptResponse:实验参数,同时开启响应拦截

注意注释里的限制:header override 不会延续到后续 redirect hop。重定向产生新请求时,需要再次处理新的 paused request。

Fetch.failRequest

让请求失败,errorReason 使用 Network.ErrorReason,例如 Aborted、TimedOut、ConnectionRefused、BlockedByClient。

常用于屏蔽资源或模拟失败。

Fetch.fulfillRequest

直接给请求提供响应,不再访问网络。

参数:

  • responseCode
  • responseHeaders
  • binaryResponseHeaders
  • body
  • responsePhrase

如果省略 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 可选:

  • Default
  • CancelAuth
  • ProvideCredentials

选择 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:大响应体转 stream
  • Emulation:离线、延迟、吞吐、连接类型等网络条件仿真
  • 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。

相关推荐
一条破秋裤21 小时前
【1115】【多线程】【笔记】
前端·chrome·笔记
stormsha1 天前
我的抓取脚本凭什么从不抢你的鼠标
前端·chrome
梯度下降者1 天前
解决Chrome路径错误问题
chrome·selenium·解决方案·webdriverexception·路径错误
MyBili2 天前
Chrome开发者工具入门:从看懂页面到高效调试
前端·chrome·谷歌浏览器·开发工具·chrome devtools·网页调式·网络请求分析
Flynt3 天前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
其实防守也摸鱼3 天前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
MyBili3 天前
Chrome多配置文件实战:工作生活身份彻底隔离管理
chrome·谷歌浏览器·使用技巧·效率工具·账号隔离·多配置文件·多身份管理
afumu5 天前
免费 API 满地都是,为什么还有人做「让网页 AI 干活」这种东西
javascript·chrome·浏览器