Puppeteer ErrorCode 类型全解析掌控 HTTPRequest.abort() 的请求中止错误语义【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerPuppeteer 的请求拦截Request Interception机制允许开发者决定每个网络请求的去向——放行、响应或直接中止。而ErrorCode正是HTTPRequest.abort()方法用于指定以何种网络错误终止该请求的类型约束。本文以仓库中 docs/api/puppeteer.errorcode.md 的类型定义为主体结合 packages/puppeteer-core/src/api/HTTPRequest.ts 的源码实现与 test/src/requestinterception.test.ts 的测试用例完整讲解ErrorCode的全部取值、其到 CDP 协议底层错误原因Network.ErrorReason的映射关系以及在实际拦截业务中的正确用法。读完你即可精确控制被中止请求在浏览器网络栈如devtools面板中呈现的错误类型并理解各取值在真实页面中的可观测表现。ErrorCode 是什么请求拦截错误码的类型约束ErrorCode是 Puppeteer 导出的一个公开字符串字面量联合类型TypeScript union type用于约束 HTTPRequest.abort() 方法传入的中止原因。它在 API 层面解决了如下问题当你在页面加载过程中拦截并中止某个请求时应以何种网络错误语义通知浏览器——是连接被拒绝域名无法解析还是网络连接已断开这种差异会直接反映在 DevTools Network 面板与页面fetch抛出的错误信息中。类型签名与源码位置文档给出的类型定义如下export type ErrorCode | aborted | accessdenied | addressunreachable | blockedbyclient | blockedbyresponse | connectionaborted | connectionclosed | connectionfailed | connectionrefused | connectionreset | internetdisconnected | namenotresolved | timedout | failed;该类型定义于 packages/puppeteer-core/src/api/HTTPRequest.ts带有public注解因此属于 Puppeteer 面向使用者的稳定公开 APIstable public API会被 API 文档生成工具自动抽取并生成上述文档页。puppeteer-core 与完整 puppeteer 包均会导出该类型供 TypeScript 使用者获得参数校验与 IDE 自动补全。设计本质CDP Network.ErrorReason 的小写驼峰化视图从源码结构看ErrorCode并非凭空定义而是底层 CDPChrome DevTools Protocol中Network.ErrorReason枚举值的一种前端化表达。开发者无需接触 CDP 原始字符串即可完成类型安全的调用同时 Puppeteer 内部再将这些小写错误码还原为 CDP 原因。这一设计让页面层 API 的易用性与协议层的精确性得以解耦。14 个取值逐一拆解错误语义与适用场景下表给出全部 14 个取值及语义供实际拦截策略设计时按需选用ErrorCode页面层 API语义典型适用场景aborted请求被中止由脚本/拦截逻辑主动终止的请求accessdenied访问被拒绝模拟服务器拒绝访问的权限类失败addressunreachable地址不可达模拟目标主机无法到达blockedbyclient被客户端拦截阻塞客户端侧如扩展、拦截器主动封禁的资源blockedbyresponse被响应内容阻塞服务端策略拒绝放行的资源connectionaborted连接被中止连接建立后被中途掐断connectionclosed连接被关闭服务器过早关闭连接connectionfailed连接失败建立连接过程整体失败connectionrefused连接被拒绝端口未监听、拒绝握手等经典场景connectionreset连接被重置RST 重置模拟被对端踢掉连接internetdisconnected网络已断开模拟断网环境见下文测试佐证namenotresolvedDNS 域名无法解析模拟 DNS 解析失败的离线/钓鱼拦截timedout请求超时模拟慢网/挂起后超时failed通用失败默认值不确定具体原因时的兜底选项各取值的语义描述基于其字面名称与 CDPNetwork.ErrorReason对应取值推断具体行为最终由底层浏览器网络栈决定。源码级证据ErrorCode 到 CDP 错误原因的映射表ErrorCode并不是直接传给 CDP 的字符串。在 packages/puppeteer-core/src/api/HTTPRequest.ts 中存在一张内部映射表errorReasons其键为页面层ErrorCode小写字符串值为 CDP 层的驼峰式原因const errorReasons: RecordErrorCode, Protocol.Network.ErrorReason { aborted: Aborted, accessdenied: AccessDenied, addressunreachable: AddressUnreachable, blockedbyclient: BlockedByClient, blockedbyresponse: BlockedByResponse, connectionaborted: ConnectionAborted, connectionclosed: ConnectionClosed, connectionfailed: ConnectionFailed, connectionrefused: ConnectionRefused, connectionreset: ConnectionReset, internetdisconnected: InternetDisconnected, namenotresolved: NameNotResolved, timedout: TimedOut, failed: Failed, } as const;由此可以看出每一个ErrorCode都能一一对应到 CDPNetwork.ErrorReason的一个合法值键值只是大小写与命名风格差异这种小写化 去分隔符的命名方式形成了强约束一旦传入不在联合类型内的字符串Record查找将返回undefined。非法错误码的防御assert 兜底映射表之所以设计成完整RecordErrorCode, ...是为了在 abort() 方法内安全地取值async abort( errorCode: ErrorCode failed, priority?: number, ): Promisevoid { this.verifyInterception(); if (!this.canBeIntercepted()) { return; } const errorReason errorReasons[errorCode]; assert(errorReason, Unknown error code: errorCode); // ... }该实现揭示三点关键行为errorCode参数可选默认值为failed即request.abort()不带参数等价于request.abort(failed)这是绝大多数测试与示例中直接调用abort()的原因若传入未知字符串会立即抛出Unknown error code: ...断言错误这是将ErrorCode定义为字面量联合类型带来的编译期 运行期双重保护必须在请求拦截启用后才能调用否则verifyInterception()会抛出异常详见下文。实战如何用 abort(errorCode) 精确控制请求中止ErrorCode的唯一直接消费者是HTTPRequest.abort()方法其公开签名为class HTTPRequest { abort(errorCode?: ErrorCode, priority?: number): Promisevoid; }在文档 docs/api/puppeteer.httprequest.abort.md 中priority被描述为若提供则拦截按协作式处理规则cooperative handling rules解析否则立即解析。前置条件必须开启请求拦截abort()的使用依赖Page.setRequestInterception()开启拦截。相关 API 见 docs/api/puppeteer.page.setrequestinterception.md。如果未开启verifyInterception()会立刻抛异常。一个完整的最小示例import puppeteer from puppeteer; const browser await puppeteer.launch(); const page await browser.newPage(); // 1. 开启请求拦截 await page.setRequestInterception(true); // 2. 在 request 事件中决定每个请求的去向 page.on(request, request { const url request.url(); if (url.endsWith(.css)) { // 默认错误码以 failed 中止样式表请求 void request.abort(); } else if (url.includes(analytics) || url.includes(ads)) { // 模拟“客户端拦截”广告/统计类请求以特定错误码中止 void request.abort(blockedbyclient); } else if (/https:\/\/tracker\.example\.com\//.test(url)) { // 模拟“DNS 解析失败”级的中止 void request.abort(namenotresolved); } else { // 其余请求放行 void request.continue(); } }); await page.goto(https://example.com/); await browser.close();通过 requestfailed 事件观察失败结果被abort()中止的请求会触发页面的requestfailed事件其failure()返回的errorText携带浏览器网络栈的错误文本。仓库测试 test/src/requestinterception.test.ts 直接验证了自定义错误码的端到端效果it(should be abortable with custom error codes, async () { const {page, server} await getTestState(); await page.setRequestInterception(true); page.on(request, request { void request.abort(internetdisconnected); }); const [failedRequest] await Promise.all([ waitEventHTTPRequest(page, requestfailed), page.goto(server.EMPTY_PAGE).catch(() {}), ]); expect(failedRequest).toBeTruthy(); expect(failedRequest.failure()!.errorText).toBe( net::ERR_INTERNET_DISCONNECTED, ); });该用例证明传入internetdisconnected后页面内fetch/导航最终呈现的底层错误文本为 Chrome 标准的net::ERR_INTERNET_DISCONNECTED即错误码确实被完整穿透到了浏览器网络栈。协作式拦截priority 参数与 ErrorCode 的组合abort()的第二个参数priority使多个拦截处理器可以协作式地竞争同一个请求的最终处置权。仓库的 test/src/requestinterception-experimental.test.ts 给出了典型调用形态void request.abort(aborted, expectedAction abort ? 1 : 0); // ... void request.abort(failed, 0); void request.abort(internetdisconnected, 0);其规则可归纳为不传priority立即解析拦截immediate resolutionabort 马上生效传入priority将该请求的InterceptResolutionAction.Abort意图与优先级记录在案当且仅当其优先级不低于已记录的其他处理意图如continue、respond时才真正以该错误码中止请求。从源码 packages/puppeteer-core/src/api/HTTPRequest.ts 可见命中最高优先级后errorReason会被暂存到interception.abortReason供最终统一处理。若你需要在多个模块各自拦截的场景中保证最高优先级的处置方说了算可同时使用abort(errorCode, priority)与 continue()、respond() 的优先级参数形成统一的处置仲裁。需要说明ErrorCode的协作式行为与优先级语义属于 Puppeteer 较新的实验性能力相关用例位于 experimental 测试文件中使用时请以当前版本实际行为为准。关联 API 速查ErrorCode 类型定义本文主体14 个合法取值一览HTTPRequest.abort()ErrorCode的唯一直接调用入口HTTPRequest.abortErrorReason()返回最近一次中止的 CDP 层Protocol.Network.ErrorReason未中止时为null可用于调试确认错误码到底映射成了哪个协议原因Page.setRequestInterception()调用abort()前必须开启的开关HTTPRequest.continue() 与 HTTPRequest.respond()与abort()并列的另外两种拦截处置方式核心实现packages/puppeteer-core/src/api/HTTPRequest.tsabort方法、packages/puppeteer-core/src/api/HTTPRequest.tserrorReasons映射表测试佐证test/src/requestinterception.test.ts默认abort()与自定义internetdisconnected的断言、test/src/requestinterception-experimental.test.ts协作式 priority 场景。小结如何选择正确的 ErrorCode把ErrorCode当作一个 14 选 1 的网络故障剧本来理解即可不关心具体故障语义只要请求不发出 → 直接用无参request.abort()等价于failed要模拟权限 / 合规拦截如广告、成人内容、违规域名→blockedbyclient或accessdenied要模拟网络环境问题断网、DNS 故障、超时→internetdisconnected、namenotresolved、timedout要模拟服务端连接故障→ 在connectionrefused、connectionreset、connectionaborted之间按需挑选多个处置方并存且需要仲裁→ 为abort(errorCode, priority)传入优先级让最高优先级的意图胜出。ErrorCode是类型定义极简、但影响链路极深的一类 API从 TypeScript 编译期的取值约束到errorReasons表的 CDP 映射再到浏览器网络栈最终的net::ERR_*文本整条链路在源码与测试中清晰可查足以支撑你在 Puppeteer 请求拦截方案中精确制造出想要的那一种网络错误。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考