ChroviaChrovia

网络请求拦截

按 URL 注册请求回调、检查解析后的请求体、取消请求，并处理 Service Worker 重启和超时。

能力：networkIntercept。API：chrovia.network。在 Provision Service Worker 使用；基本拦截不需要 EP 配置。

注册处理器

在 background.js 顶层注册，确保每次 Worker 启动都会执行：

const network = globalThis.chrovia?.network;
if (network) {
  network.intercept({ urls: ['https://example.com/api/*'], timeout: 30 }, request => {
    return request.method === 'POST' ? { cancel: true } : {};
  });
}

将 URL 替换为你控制的测试接口。在打开页面前注册，或测试前刷新已打开页面。已有标签页可能要刷新后才受规则覆盖，也不保证拦截所有浏览器内部或扩展流量。

选项与返回约定

项目含义
urls与完整 URL（含查询参数）匹配的通配字符串数组
timeout秒数；缺失、无效、非正数时默认 30；正数限制在 0.1–600
回调返回 {}原样转发请求
回调返回 {cancel: true}取消请求
stopIntercepting()清除整个拦截会话并释放等待中的请求

模式匹配完整 URL，区分大小写。* 匹配零个或多个字符，? 匹配零个或一个字符，反斜杠用于转义下一个字符。这不是正则或 Chrome 扩展匹配模式语法。

要匹配字面查询分隔符，模式值使用 https://example.com/api\?mode=*；在 JavaScript 中写成 'https://example.com/api\\?mode=*'，在 JSON 中写成 "https://example.com/api\\?mode=*"。代码中的两个反斜杠会生成模式中的一个反斜杠。除非确实需要广泛匹配，否则使用具体主机和路径，而不是 *。

intercept() 和 stopIntercepting() 返回 undefined，没有注册就绪 Promise；await intercept(...) 不能保证浏览器端已就绪。回调本身可以返回 Promise。抛错、Promise 拒绝及超时会原样放行，因此它不是失败时默认拒绝的安全屏障。

回调只能放行或取消原请求。返回替换请求头、URL、请求体或自定义响应都会被忽略。静态请求规则使用 DNR，主框架路由使用导航重定向。

请求数据

字段类型与含义
url、method、referrer描述请求的字符串
type请求目标类型，例如 document、iframe、image、script、style，fetch/XHR 为 empty；不是 DNR 的 main_frame / sub_frame 名称
timestampUnix 毫秒
requestHeaders{name, value} 数组
requestBody可选的已解析 JSON 值或表单字典
currentUsername可选的、从该框架密码管理流程捕获的用户名

application/json 请求体是解析后的 JSON 值，不是原始字符串。application/x-www-form-urlencoded 中每个字段对应字符串数组，保留重复字段。只解析不超过 1 MiB 的内存字节请求体。空内容、不支持的类型、文件或流、超大请求体、无效 JSON 都可能没有 requestBody。它不是通用上传捕获 API，不要记录凭据请求体。

取消时的界面

默认取消使用 ERR_ABORTED，导航通常静默停止。需要 Chromium 的 blocked-by-client 错误行为时，配置：

{
  "internal": {
    "network_intercept": {
      "cancel_as": "blocked_by_client"
    }
  }
}

其他值使用默认行为。按需合并并签名 EP，然后重启。这只影响错误码，不改变回调决定或超时策略。

Service Worker 使用注意事项

使用一个插件负责拦截。后一次 intercept() 调用会替换该浏览器实例之前的处理器和规则。

在脚本顶层注册，不要只在 onInstalled 中注册，也不要依赖全局变量跨 Worker 重启保留。匹配请求可以唤醒 Worker，期间仍适用配置的超时时间。回调因 Worker 停止而中断时，请求会原样继续。调用 stopIntercepting() 停止拦截。

在可丢弃的测试接口上验证 GET 与 POST、Worker 休眠唤醒、错误和超时。即使 API 对象存在，注册前打开的页面也可能需要刷新。