Puppeteer HTTPRequest.interceptResolutionState() 方法解析：理解请求拦截决议状态与优先级机制

HTTPRequest.interceptResolutionState() 是 Puppeteer 请求拦截（Request Interception）体系中用于观测"当前拦截决议状态"的关键查询方法。它返回一个 InterceptResolutionState 对象，说明当前请求的决议动作（action）与优先级（priority）。阅读完本文，你将能厘清 abort、respond、continue、disabled、none、already-handled 六种决议状态的确切语义，理解优先级的比较规则，并掌握如何在多拦截处理器协同场景下准确判断请求的最终走向。

方法签名与返回类型

依据 docs/api/puppeteer.httprequest.interceptresolutionstate.md，该方法的签名如下：

class HTTPRequest {
  interceptResolutionState(): InterceptResolutionState;
}

interceptResolutionState() 不接收任何参数，直接返回一个描述当前解析动作与优先级的 InterceptResolutionState 对象。该方法在 HTTPRequest 类的抽象实现中定义，CDP 与 WebDriver BiDi 两条协议线的 HTTPRequest 实现都会继承这一查询逻辑，因此在 puppeteer-core 的 Chrome 与 Firefox 场景下均可使用。

返回对象由 InterceptResolutionState 接口定义，见 puppeteer.interceptresolutionstate.md 及 源码：

字段	类型	修饰符	含义
action	InterceptResolutionAction	必选	当前决议动作，枚举字符串值
priority	number	可选	该决议对应的优先级；无优先级时字段不存在

priority 为可选字段——当决议动作是 disabled、none 或 already-handled 时，返回对象中通常不含 priority，这也是为何读取前应先判断 action 或使用可选链/'priority' in state 判定的原因。

六种决议动作（action）语义

action 字段取值为 InterceptResolutionAction 枚举 的成员之一，其字符串定义可在 源码枚举声明中逐一对齐：

枚举成员	字符串值	语义
Abort	"abort"	已有处理器决定中止该请求（通常来自 request.abort()）
Respond	"respond"	已有处理器决定用自定义响应伪造该请求（来自 request.respond()）
Continue	"continue"	已有处理器决定放行该请求（来自 request.continue()）
Disabled	"disabled"	该请求的拦截处于关闭状态，当前无法拦截
None	"none"	拦截已启用，但还没有任何处理器给出决议动作
AlreadyHandled	"already-handled"	该请求已被某个处理器实际处理过（请求已被 handle）

内部决议状态的优先级判定逻辑

三个"即时返回"分支

从实现看，interceptResolutionState() 本身是一个"只读快照"查询，它并不直接读取某个单一字段，而是按以下顺序收敛出对外返回结果（源码位置）：

1. 若 interception.enabled === false，直接返回 { action: Disabled } —— 即未通过 page.setRequestInterception(true) 启用拦截时，所有请求都处于 disabled 状态；
2. 若 interception.handled === true，直接返回 { action: AlreadyHandled } —— 请求已被某个处理器 handle，之后新注册的处理器再查询都会得到 already-handled；
3. 否则返回内部 interception.resolutionState 的浅拷贝 {...this.interception.resolutionState}。

内部状态字段（源码）的初始值为 action: InterceptResolutionAction.None 且不含 priority，即"拦截已启用但尚无决议"，对应第 3 种动作 none。

决议如何写入

action 与 priority 的写入完全由 continue()、respond()、abort() 三个公开方法在传入 priority 参数时触发（不传 priority 则立即执行底层协议动作，不走决议状态机）：

• continue(overrides, priority)：源码 中，仅当 priority 大于既有决议优先级时覆盖为 {action: Continue, priority}；若相等则仅当既有动作既非 abort 也非 respond 时才更新为 Continue；
• respond(response, priority)：源码 中，优先于 Continue（同优先级时 respond 会覆盖 continue），但会被 abort 压制；
• abort(errorCode, priority)：源码 中，abort 优先级最高——使用 >= 比较，同优先级即可覆盖任何既有决议。

由此可以归纳 Puppeteer 的协作式（cooperative）决议优先级排序：abort 最高，respond 次之，continue 最低。当多个处理器以相同 priority 对同一请求竞争时，冲突规则是 "abort > respond > continue"。

最终决议如何生效

写入的状态并非立即执行，而是在所有入队处理器执行完毕后的 finalizeInterceptions() 中兑现（源码）：它先等待 enqueueInterceptAction() 入队的全部异步处理器 resolve，再根据 interceptResolutionState() 读取出的最终 action 分发——abort 走 _abort()、respond 走 _respond()、continue 走 _continue()。

优先级默认值：DEFAULT_INTERCEPT_RESOLUTION_PRIORITY

Puppeteer 同时导出一个默认优先级常量（源码）：

export const DEFAULT_INTERCEPT_RESOLUTION_PRIORITY = 0;

当你在 page.on('request', ...) 中调用 request.continue({}, DEFAULT_INTERCEPT_RESOLUTION_PRIORITY) 时，意味着以"0 号默认优先级"参与协作式决议。例如在 test/src/requestinterception-experimental.test.ts 中即使用 void request.continue({}, 0) 对 document 请求放行。你既可以直接使用该常量，也可以自行约定更大的数值实现"更高优先级的拦截逻辑"。

与相关方法的配合使用

• isInterceptResolutionHandled()：返回 this.interception.handled 布尔值，用于判断该请求是否已被处理。interceptResolutionState().action === 'already-handled' 与它为 true 是等价的两个视角（源码）；
• continueRequestOverrides()、responseForRequest()、abortErrorReason()：分别暴露 continue、respond、abort 待用的覆盖参数，便于其他处理器"观察并接续"决议内容。

典型使用场景

场景一：多处理器下判断请求是否已被他人处理

拦截启用后，为同一事件注册多个 request 监听器是很常见的需求。由于监听器按注册顺序同步触发，后注册的处理器可能遇到请求已被前一个处理器 handle 的情形。参考 测试用例，可以这样读取状态：

import puppeteer from 'puppeteer';
import {InterceptResolutionAction} from 'puppeteer-core'; // 或按你的导入方式引入

const browser = await puppeteer.launch();
const page = await browser.newPage();

await page.setRequestInterception(true);

page.on('request', request => {
  void request.continue(); // 第一个处理器先 handle 请求
});

page.on('request', request => {
  const {action} = request.interceptResolutionState();
  if (action === InterceptResolutionAction.AlreadyHandled) {
    console.log(`请求 ${request.url()} 已被先前处理器处理，跳过重复逻辑`);
    return;
  }
  // 未被处理时，再结合本处理器逻辑做决议
});

场景二：组合过滤与 MOCK，读取最终决议

结合拦截的经典用法，可在业务回调里实现"放行 + Mock 响应"的混合策略，并通过 interceptResolutionState() 做日志/断言：

await page.setRequestInterception(true);

page.on('request', request => {
  const {action} = request.interceptResolutionState();

  if (request.url().endsWith('/api/mock')) {
    request.respond({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ok: true}),
    });
    return;
  }
  request.continue();
});

注意事项（与源码约束一致）：

• 拦截必须先用 page.setRequestInterception(true) 开启，否则 continue/respond/abort 会抛出 "Request Interception is not enabled!" 异常（由 verifyInterception 强制校验），此时查询到的 action 恒为 disabled；
• 若请求已被 handle，再次调用 continue/respond/abort 会抛出 "Request is already handled!" 异常，因此协同处理器务必先通过 interceptResolutionState() 或 isInterceptResolutionHandled() 做保护判断；
• 对 dataURL 请求调用 respond() 是 noop，不产生任何效果（源码注释已注明，见 respond 文档注释）。

小结

interceptResolutionState() 是 Puppeteer 协作式请求拦截机制中最重要的"状态观测点"：它以统一的 {action, priority?} 结构，对外呈现"拦截是否启用、是否已处理、当前最高优先级决议是什么"三方面信息；其背后的六种动作枚举与 "abort > respond > continue" 的优先级冲突规则，决定了多处理器场景下每个网络请求的最终命运。理解这一方法，是编写健壮的请求拦截、流量 Mock 与广告/追踪屏蔽逻辑的前提。