 深度实战指南)
Puppeteer 请求拦截与改写核心 APIHTTPRequest.continue() 深度实战指南【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本文以 docs/api/puppeteer.httprequest.continue.md 为骨架系统讲解 PuppeteerJavaScript API for Chrome and Firefox中HTTPRequest.continue()的使用方式与底层原理。该方法与Page.setRequestInterception()配合是拦截并改写页面发出的任意 HTTP 请求Header、URL、Method、POST Body的标准入口是广告过滤、Mock 数据、请求降级与跨域改造类爬虫/自动化脚本的核心设施。读完本文你将掌握请求拦截的完整调用链、ContinueRequestOverrides的四个可改写字段、可选的协作式优先级语义cooperative interception以及 CDP 与 WebDriver BiDi 两种协议通道下的真实实现差异。为什么需要 continue()一次请求、三种归宿在现代浏览器自动化场景中监听请求只是第一步真正的难点是在请求真正发出前改写它。Puppeteer 为此设计了请求拦截request interception机制当通过 Page.setRequestInterception() 开启拦截后页面的每个网络请求都会被挂起stall直到开发者显式地给出处理结论。结论只有三种request.abort()—— 终止该请求例如拦截图片、屏蔽追踪域名request.respond()—— 伪造响应直接返回本地 Mock 数据请求不会到达服务器request.continue()—— 放行请求并且允许在放行前对请求本身做改写这是本文主角。从源码注释看三者是并列的处理动作InterceptResolutionAction枚举同时收录了abort | respond | continue另有disabled | none | already-handled三种状态值见 packages/puppeteer-core/src/api/HTTPRequest.ts。而拦截的终结发生在finalizeInterceptions()它会先依次执行入队的处理器再根据最终决议动作分别调用_abort()、_respond()或_continue()见 packages/puppeteer-core/src/api/HTTPRequest.ts。continue()正是触发_continue()这一底层放行通道的公共 API。方法签名与核心语义官方 API 文档给出的完整签名如下docs/api/puppeteer.httprequest.continue.mdclass HTTPRequest { continue( overrides?: ContinueRequestOverrides, priority?: number, ): Promisevoid; }该方法属于HTTPRequest实例由page.on(request, req ...)事件回调提供返回Promisevoid。两个参数都可选。语义要点无参调用request.continue()即原样放行等价于不改写任何字段传入overrides则按需改写 URL、Method、PostData 或 Headers传入priority则走协作式拦截决议见下文专节否则立即执行放行。在 packages/puppeteer-core/src/api/HTTPRequest.ts 中的真实实现证实了这一语义continue()首先调用verifyInterception()做前置校验然后判断canBeIntercepted()通过后若未提供priority直接await this._continue(overrides)立即放行。前置条件必须先开启请求拦截文档的 Remarks 部分明确强调了两点docs/api/puppeteer.httprequest.continue.mdTo use this, request interception should be enabled withPage.setRequestInterception(). Exception is immediately thrown if the request interception is not enabled.必须先调用page.setRequestInterception(true)若拦截未开启却调用continue()会立即抛出异常。异常的具体文案藏在源码的verifyInterception()中packages/puppeteer-core/src/api/HTTPRequest.tsprotected verifyInterception(): void { assert(this.interception.enabled, Request Interception is not enabled!); assert(!this.interception.handled, Request is already handled!); }即未开启时抛Request Interception is not enabled!请求已被处理过例如已被abort/respond/continue命中再次调用时抛Request is already handled!。后者是新手最常见的报错来源——一个请求只能被处理一次。哪些请求可以被 continue拦截并非对所有请求生效。canBeIntercepted()的实现给出了边界packages/puppeteer-core/src/cdp/HTTPRequest.tsprotected canBeIntercepted(): boolean { return !this.url().startsWith(data:) !this._fromMemoryCache; }data:协议的请求内联图片等 data URL不可拦截命中浏览器内存缓存memory cache的请求不可拦截。当canBeIntercepted()返回false时continue()会静默直接返回而不报错。另外需注意HTTP 层面成功的 404/503 等错误响应仍属于可被正常放行的请求只有真正失败如net::ERR_FAILED才会走requestfailed事件路径。改写参数ContinueRequestOverrides 逐字段拆解overrides的类型为ContinueRequestOverrides它只包含四个可选字段定义见 packages/puppeteer-core/src/api/HTTPRequest.ts属性表见 docs/api/puppeteer.continuerequestoverrides.md字段类型说明与默认值headersRecordstring, string可选覆盖请求头值为undefined表示删除该请求头。不传则保持原请求头。methodstring可选改写请求方法如GET、POST。不传则保持原方法。postDatastring可选改写 POST 请求体。仅对带 body 的方法有意义。不传则保持原请求体。urlstring可选改写目标 URL。注意这只是改变请求的 URL并非重定向This is not a redirect不会触发 3xx 跳转语义。不传则保持原 URL。要点提示headers中的 key 一律小写处理。官方文档示例中request.headers()返回的头部键已全部是小写因此用Object.assign({}, request.headers(), ...)做增量修改是最安全的做法postData字段为字符串。注意获取侧 APIrequest.postData()已标记deprecated官方推荐改用request.fetchPostData()获取完整 body见 docs/api/puppeteer.httprequest.fetchpostdata.md 与 docs/api/puppeteer.httprequest.postdata.md——当 body 过长或不易解码时postData()可能返回undefined此时应使用fetchPostData()。实战一改写与删除请求头文档示例官方文档给出的典型用法是读原头 → 改头 → continuedocs/api/puppeteer.httprequest.continue.mdawait page.setRequestInterception(true); page.on(request, request { // Override headers const headers Object.assign({}, request.headers(), { foo: bar, // set foo header origin: undefined, // remove origin header }); request.continue({headers}); });这段代码演示了continue()的两个独特能力新增请求头把foo头置为bar删除请求头把origin置为undefined—— 注意这里并不是把值置成字符串undefined而是语义化的移除。这一约定在类型Recordstring, string之外的取值空间中通过底层序列化逻辑实现。实战二改写 URL、方法与请求体continue()的四个字段可自由组合。例如把某次表单提交从 GET 改写为 POST 并携带新 body或把资源请求指向本地镜像await page.setRequestInterception(true); page.on(request, request { if (request.url().includes(/api/v2/legacy)) { // 改写目标地址不触发重定向而是直接发出新 URL 的请求 request.continue({url: https://example.com/api/v3/legacy}); } else if (request.url().endsWith(/login)) { request.continue({ method: POST, postData: usernameadminfrominterceptor, headers: { ...request.headers(), content-type: application/x-www-form-urlencoded, }, }); } else { request.continue(); // 其余请求原样放行这一分支必不可少 } });⚠️ 若开启了拦截却没有对某请求调用continue()/respond()/abort()该请求会一直挂起直到超时。文档 Page.setRequestInterception() 明确写道Once request interception is enabled, every request will stall unless its continued, responded or aborted; or completed using the browser cache.因此拦截处理器必须保证每个请求都有归宿。底层实现CDP 与 WebDriver BiDi 双通道Puppeteer 当前同时支持 ChromeCDP 协议与 FirefoxWebDriver BiDi 协议_continue()的协议层实现因此存在两套。这一事实可直接从仓库源码确认。CDP 通道Fetch.continueRequestCDP 实现位于 packages/puppeteer-core/src/cdp/HTTPRequest.tsasync _continue(overrides: ContinueRequestOverrides {}): Promisevoid { const {url, method, postData, headers} overrides; this.interception.handled true; const postDataBinaryBase64 postData ? stringToBase64(postData) : undefined; if (this._interceptionId undefined) { throw new Error( HTTPRequest is missing _interceptionId needed for Fetch.continueRequest, ); } await this.#client .send(Fetch.continueRequest, { requestId: this._interceptionId, url, method, postData: postDataBinaryBase64, headers: headers ? headersArray(headers) : undefined, }) .catch(error { this.interception.handled false; return handleError(error, this.#logger); }); }值得注意的实现细节底层走的是 Chrome DevTools Protocol 的Fetch.continueRequest域调用requestId即该请求的拦截 ID_interceptionIdpostData字符串先经stringToBase64()转成base64再传给协议层因为 CDP 的 Fetch 域要求 base64 编码的 bodyheaders经headersArray()序列化为协议要求的键值数组值为undefined的头部正是在序列化层被剔除从而实现删头语义错误回滚协议调用失败时会把interception.handled复位为false并记录日志意味着该请求仍可被后续处理器重新处理而不是卡死在已处理状态若_interceptionId缺失如该请求本不可被拦截则抛错说明。WebDriver BiDi 通道request.continueRequestBiDiFirefox实现位于 packages/puppeteer-core/src/bidi/HTTPRequest.ts同样是先标记handled true再调用this.#request.continueRequest(...)body 以结构化{type, value}形式而非 CDP 的 base64 字符串传递override async _continue(overrides: ContinueRequestOverrides {}): Promisevoid { const headers: Bidi.Network.Header[] getBidiHeaders(overrides.headers); this.interception.handled true; return await this.#request.continueRequest({ url: overrides.url, method: overrides.method, body: overrides.postData ? { /* ...结构化 body... */ } : undefined, headers, }); }因此上层 API 一致、下层协议自适应是本方法的架构特点无论浏览器走 CDP 还是 BiDi开发者写的request.continue({...})代码都无需变化。协作式拦截priority 参数与决议规则continue()的第二个参数priority是 Puppeteer 较新的高级特性。文档原话docs/api/puppeteer.httprequest.continue.mdIf provided, intercept is resolved using cooperative handling rules. Otherwise, intercept is resolved immediately.立即决议模式不传 priority不传priority时continue()直接执行_continue()放行请求。与此同时若页面事件流中另有一个处理器调用了respond()二者会产生竞态——后执行的调用很可能触发Request is already handled!异常。这正是引入协作模式的原因。协作决议模式传 priority传priority时continue()不会立即放行而是先登记意图把本次overrides存入interception.requestOverrides再与已登记的其它动作按优先级协商实现见 packages/puppeteer-core/src/api/HTTPRequest.ts。规则如下若此前没有更高优先级的动作把决议动作置为Continue并记录本次 priority若本次 priority高于已登记动作则覆盖为Continue若 priority相等当已登记动作是abort或respond时保持原动作中止/伪响应优先于放行否则置为Continueabort()/respond()同样支持 priority最终谁胜出由数值大小决定。该机制允许多个独立的拦截处理器如广告拦截扩展与业务 Mock 中间件各自声明优先级而不会互相踩踏。仓库为此提供了默认常量与配套方法DEFAULT_INTERCEPT_RESOLUTION_PRIORITY 0packages/puppeteer-core/src/api/HTTPRequest.ts测试中普遍使用request.continue({}, 0)这样的写法request.continueRequestOverrides()可读取将被用于放行的 overridespackages/puppeteer-core/src/api/HTTPRequest.tsrequest.interceptResolutionState()返回{action, priority}决议快照packages/puppeteer-core/src/api/HTTPRequest.tsrequest.enqueueInterceptAction(handler)可把异步处理器加入队列保证在拦截被 finalize 前全部执行完毕packages/puppeteer-core/src/api/HTTPRequest.ts。协作式语义并非纸上谈兵仓库自带的实验性测试 test/src/requestinterception-experimental.test.ts 中大量出现request.continue({}, 0)与request.abort(aborted, 1)、request.respond({...}, 1)混用的场景通过数值优先级验证高优先级 abort/respond 覆盖低优先级 continue的决议结果可作为理解该机制的活教材。最佳实践与常见坑位清单最后把容易踩坑的点汇总如下先开闸再改写忘记await page.setRequestInterception(true)就调用continue()会同步抛出Request Interception is not enabled!异常发生在verifyInterception()阶段packages/puppeteer-core/src/api/HTTPRequest.ts每请求必有归宿拦截开启后所有请求默认挂起else分支务必补request.continue()一请求一处理同一请求多次调用任意处理 API 会抛Request is already handled!需要多个处理器共同决定时应走priority协作模式或enqueueInterceptAction()URL 改写不是重定向overrides.url只改变本次发出的请求地址不产生 3xx 跳转链也不会改变浏览器地址栏删除头部用undefined在 headers 对象中将某键设为undefined才能在序列化时移除该头直接传空字符串可能会被当作合法值发送边界请求放行受限data:URL 与命中内存缓存的请求不可被拦截continue()对它们会静默跳过保持事件监听优先注册page.on(request, ...)的处理器应在page.goto()等导航动作之前注册避免页面首屏请求在监听器就绪前已经发出需要保持单页长期监听时通常选择在创建 page 后立即开启拦截。进一步阅读拦截开关与全流程查看 Page.setRequestInterception() 文档其中附有终止所有图片请求的完整示例兄弟 API对比阅读 HTTPRequest.abort()终止请求与 HTTPRequest.respond()伪响应覆盖参数类型见 ContinueRequestOverrides 接口文档底层调用链实现见 packages/puppeteer-core/src/api/HTTPRequest.ts、packages/puppeteer-core/src/cdp/HTTPRequest.ts、packages/puppeteer-core/src/bidi/HTTPRequest.ts浏览器差异化支持说明见 docs/webdriver-bidi.md 与 docs/supported-browsers.md。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puppeteer 请求拦截与改写核心 API：HTTPRequest.continue() 深度实战指南
Puppeteer 请求拦截与改写核心 APIHTTPRequest.continue() 深度实战指南【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本文以 docs/api/puppeteer.httprequest.continue.md 为骨架系统讲解 PuppeteerJavaScript API for Chrome and Firefox中HTTPRequest.continue()的使用方式与底层原理。该方法与Page.setRequestInterception()配合是拦截并改写页面发出的任意 HTTP 请求Header、URL、Method、POST Body的标准入口是广告过滤、Mock 数据、请求降级与跨域改造类爬虫/自动化脚本的核心设施。读完本文你将掌握请求拦截的完整调用链、ContinueRequestOverrides的四个可改写字段、可选的协作式优先级语义cooperative interception以及 CDP 与 WebDriver BiDi 两种协议通道下的真实实现差异。为什么需要 continue()一次请求、三种归宿在现代浏览器自动化场景中监听请求只是第一步真正的难点是在请求真正发出前改写它。Puppeteer 为此设计了请求拦截request interception机制当通过 Page.setRequestInterception() 开启拦截后页面的每个网络请求都会被挂起stall直到开发者显式地给出处理结论。结论只有三种request.abort()—— 终止该请求例如拦截图片、屏蔽追踪域名request.respond()—— 伪造响应直接返回本地 Mock 数据请求不会到达服务器request.continue()—— 放行请求并且允许在放行前对请求本身做改写这是本文主角。从源码注释看三者是并列的处理动作InterceptResolutionAction枚举同时收录了abort | respond | continue另有disabled | none | already-handled三种状态值见 packages/puppeteer-core/src/api/HTTPRequest.ts。而拦截的终结发生在finalizeInterceptions()它会先依次执行入队的处理器再根据最终决议动作分别调用_abort()、_respond()或_continue()见 packages/puppeteer-core/src/api/HTTPRequest.ts。continue()正是触发_continue()这一底层放行通道的公共 API。方法签名与核心语义官方 API 文档给出的完整签名如下docs/api/puppeteer.httprequest.continue.mdclass HTTPRequest { continue( overrides?: ContinueRequestOverrides, priority?: number, ): Promisevoid; }该方法属于HTTPRequest实例由page.on(request, req ...)事件回调提供返回Promisevoid。两个参数都可选。语义要点无参调用request.continue()即原样放行等价于不改写任何字段传入overrides则按需改写 URL、Method、PostData 或 Headers传入priority则走协作式拦截决议见下文专节否则立即执行放行。在 packages/puppeteer-core/src/api/HTTPRequest.ts 中的真实实现证实了这一语义continue()首先调用verifyInterception()做前置校验然后判断canBeIntercepted()通过后若未提供priority直接await this._continue(overrides)立即放行。前置条件必须先开启请求拦截文档的 Remarks 部分明确强调了两点docs/api/puppeteer.httprequest.continue.mdTo use this, request interception should be enabled withPage.setRequestInterception(). Exception is immediately thrown if the request interception is not enabled.必须先调用page.setRequestInterception(true)若拦截未开启却调用continue()会立即抛出异常。异常的具体文案藏在源码的verifyInterception()中packages/puppeteer-core/src/api/HTTPRequest.tsprotected verifyInterception(): void { assert(this.interception.enabled, Request Interception is not enabled!); assert(!this.interception.handled, Request is already handled!); }即未开启时抛Request Interception is not enabled!请求已被处理过例如已被abort/respond/continue命中再次调用时抛Request is already handled!。后者是新手最常见的报错来源——一个请求只能被处理一次。哪些请求可以被 continue拦截并非对所有请求生效。canBeIntercepted()的实现给出了边界packages/puppeteer-core/src/cdp/HTTPRequest.tsprotected canBeIntercepted(): boolean { return !this.url().startsWith(data:) !this._fromMemoryCache; }data:协议的请求内联图片等 data URL不可拦截命中浏览器内存缓存memory cache的请求不可拦截。当canBeIntercepted()返回false时continue()会静默直接返回而不报错。另外需注意HTTP 层面成功的 404/503 等错误响应仍属于可被正常放行的请求只有真正失败如net::ERR_FAILED才会走requestfailed事件路径。改写参数ContinueRequestOverrides 逐字段拆解overrides的类型为ContinueRequestOverrides它只包含四个可选字段定义见 packages/puppeteer-core/src/api/HTTPRequest.ts属性表见 docs/api/puppeteer.continuerequestoverrides.md字段类型说明与默认值headersRecordstring, string可选覆盖请求头值为undefined表示删除该请求头。不传则保持原请求头。methodstring可选改写请求方法如GET、POST。不传则保持原方法。postDatastring可选改写 POST 请求体。仅对带 body 的方法有意义。不传则保持原请求体。urlstring可选改写目标 URL。注意这只是改变请求的 URL并非重定向This is not a redirect不会触发 3xx 跳转语义。不传则保持原 URL。要点提示headers中的 key 一律小写处理。官方文档示例中request.headers()返回的头部键已全部是小写因此用Object.assign({}, request.headers(), ...)做增量修改是最安全的做法postData字段为字符串。注意获取侧 APIrequest.postData()已标记deprecated官方推荐改用request.fetchPostData()获取完整 body见 docs/api/puppeteer.httprequest.fetchpostdata.md 与 docs/api/puppeteer.httprequest.postdata.md——当 body 过长或不易解码时postData()可能返回undefined此时应使用fetchPostData()。实战一改写与删除请求头文档示例官方文档给出的典型用法是读原头 → 改头 → continuedocs/api/puppeteer.httprequest.continue.mdawait page.setRequestInterception(true); page.on(request, request { // Override headers const headers Object.assign({}, request.headers(), { foo: bar, // set foo header origin: undefined, // remove origin header }); request.continue({headers}); });这段代码演示了continue()的两个独特能力新增请求头把foo头置为bar删除请求头把origin置为undefined—— 注意这里并不是把值置成字符串undefined而是语义化的移除。这一约定在类型Recordstring, string之外的取值空间中通过底层序列化逻辑实现。实战二改写 URL、方法与请求体continue()的四个字段可自由组合。例如把某次表单提交从 GET 改写为 POST 并携带新 body或把资源请求指向本地镜像await page.setRequestInterception(true); page.on(request, request { if (request.url().includes(/api/v2/legacy)) { // 改写目标地址不触发重定向而是直接发出新 URL 的请求 request.continue({url: https://example.com/api/v3/legacy}); } else if (request.url().endsWith(/login)) { request.continue({ method: POST, postData: usernameadminfrominterceptor, headers: { ...request.headers(), content-type: application/x-www-form-urlencoded, }, }); } else { request.continue(); // 其余请求原样放行这一分支必不可少 } });⚠️ 若开启了拦截却没有对某请求调用continue()/respond()/abort()该请求会一直挂起直到超时。文档 Page.setRequestInterception() 明确写道Once request interception is enabled, every request will stall unless its continued, responded or aborted; or completed using the browser cache.因此拦截处理器必须保证每个请求都有归宿。底层实现CDP 与 WebDriver BiDi 双通道Puppeteer 当前同时支持 ChromeCDP 协议与 FirefoxWebDriver BiDi 协议_continue()的协议层实现因此存在两套。这一事实可直接从仓库源码确认。CDP 通道Fetch.continueRequestCDP 实现位于 packages/puppeteer-core/src/cdp/HTTPRequest.tsasync _continue(overrides: ContinueRequestOverrides {}): Promisevoid { const {url, method, postData, headers} overrides; this.interception.handled true; const postDataBinaryBase64 postData ? stringToBase64(postData) : undefined; if (this._interceptionId undefined) { throw new Error( HTTPRequest is missing _interceptionId needed for Fetch.continueRequest, ); } await this.#client .send(Fetch.continueRequest, { requestId: this._interceptionId, url, method, postData: postDataBinaryBase64, headers: headers ? headersArray(headers) : undefined, }) .catch(error { this.interception.handled false; return handleError(error, this.#logger); }); }值得注意的实现细节底层走的是 Chrome DevTools Protocol 的Fetch.continueRequest域调用requestId即该请求的拦截 ID_interceptionIdpostData字符串先经stringToBase64()转成base64再传给协议层因为 CDP 的 Fetch 域要求 base64 编码的 bodyheaders经headersArray()序列化为协议要求的键值数组值为undefined的头部正是在序列化层被剔除从而实现删头语义错误回滚协议调用失败时会把interception.handled复位为false并记录日志意味着该请求仍可被后续处理器重新处理而不是卡死在已处理状态若_interceptionId缺失如该请求本不可被拦截则抛错说明。WebDriver BiDi 通道request.continueRequestBiDiFirefox实现位于 packages/puppeteer-core/src/bidi/HTTPRequest.ts同样是先标记handled true再调用this.#request.continueRequest(...)body 以结构化{type, value}形式而非 CDP 的 base64 字符串传递override async _continue(overrides: ContinueRequestOverrides {}): Promisevoid { const headers: Bidi.Network.Header[] getBidiHeaders(overrides.headers); this.interception.handled true; return await this.#request.continueRequest({ url: overrides.url, method: overrides.method, body: overrides.postData ? { /* ...结构化 body... */ } : undefined, headers, }); }因此上层 API 一致、下层协议自适应是本方法的架构特点无论浏览器走 CDP 还是 BiDi开发者写的request.continue({...})代码都无需变化。协作式拦截priority 参数与决议规则continue()的第二个参数priority是 Puppeteer 较新的高级特性。文档原话docs/api/puppeteer.httprequest.continue.mdIf provided, intercept is resolved using cooperative handling rules. Otherwise, intercept is resolved immediately.立即决议模式不传 priority不传priority时continue()直接执行_continue()放行请求。与此同时若页面事件流中另有一个处理器调用了respond()二者会产生竞态——后执行的调用很可能触发Request is already handled!异常。这正是引入协作模式的原因。协作决议模式传 priority传priority时continue()不会立即放行而是先登记意图把本次overrides存入interception.requestOverrides再与已登记的其它动作按优先级协商实现见 packages/puppeteer-core/src/api/HTTPRequest.ts。规则如下若此前没有更高优先级的动作把决议动作置为Continue并记录本次 priority若本次 priority高于已登记动作则覆盖为Continue若 priority相等当已登记动作是abort或respond时保持原动作中止/伪响应优先于放行否则置为Continueabort()/respond()同样支持 priority最终谁胜出由数值大小决定。该机制允许多个独立的拦截处理器如广告拦截扩展与业务 Mock 中间件各自声明优先级而不会互相踩踏。仓库为此提供了默认常量与配套方法DEFAULT_INTERCEPT_RESOLUTION_PRIORITY 0packages/puppeteer-core/src/api/HTTPRequest.ts测试中普遍使用request.continue({}, 0)这样的写法request.continueRequestOverrides()可读取将被用于放行的 overridespackages/puppeteer-core/src/api/HTTPRequest.tsrequest.interceptResolutionState()返回{action, priority}决议快照packages/puppeteer-core/src/api/HTTPRequest.tsrequest.enqueueInterceptAction(handler)可把异步处理器加入队列保证在拦截被 finalize 前全部执行完毕packages/puppeteer-core/src/api/HTTPRequest.ts。协作式语义并非纸上谈兵仓库自带的实验性测试 test/src/requestinterception-experimental.test.ts 中大量出现request.continue({}, 0)与request.abort(aborted, 1)、request.respond({...}, 1)混用的场景通过数值优先级验证高优先级 abort/respond 覆盖低优先级 continue的决议结果可作为理解该机制的活教材。最佳实践与常见坑位清单最后把容易踩坑的点汇总如下先开闸再改写忘记await page.setRequestInterception(true)就调用continue()会同步抛出Request Interception is not enabled!异常发生在verifyInterception()阶段packages/puppeteer-core/src/api/HTTPRequest.ts每请求必有归宿拦截开启后所有请求默认挂起else分支务必补request.continue()一请求一处理同一请求多次调用任意处理 API 会抛Request is already handled!需要多个处理器共同决定时应走priority协作模式或enqueueInterceptAction()URL 改写不是重定向overrides.url只改变本次发出的请求地址不产生 3xx 跳转链也不会改变浏览器地址栏删除头部用undefined在 headers 对象中将某键设为undefined才能在序列化时移除该头直接传空字符串可能会被当作合法值发送边界请求放行受限data:URL 与命中内存缓存的请求不可被拦截continue()对它们会静默跳过保持事件监听优先注册page.on(request, ...)的处理器应在page.goto()等导航动作之前注册避免页面首屏请求在监听器就绪前已经发出需要保持单页长期监听时通常选择在创建 page 后立即开启拦截。进一步阅读拦截开关与全流程查看 Page.setRequestInterception() 文档其中附有终止所有图片请求的完整示例兄弟 API对比阅读 HTTPRequest.abort()终止请求与 HTTPRequest.respond()伪响应覆盖参数类型见 ContinueRequestOverrides 接口文档底层调用链实现见 packages/puppeteer-core/src/api/HTTPRequest.ts、packages/puppeteer-core/src/cdp/HTTPRequest.ts、packages/puppeteer-core/src/bidi/HTTPRequest.ts浏览器差异化支持说明见 docs/webdriver-bidi.md 与 docs/supported-browsers.md。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
