# 网络请求拦截

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

Source: https://console.getchrovia.com/zh/docs/sdk-network-intercept

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

## 注册处理器

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

```js
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](https://console.getchrovia.com/zh/docs/sdk-declarative-net-request)，主框架路由使用[导航重定向](https://console.getchrovia.com/zh/docs/sdk-navigation-redirect)。

## 请求数据

| 字段 | 类型与含义 |
| --- | --- |
| `url`、`method`、`referrer` | 描述请求的字符串 |
| `type` | 请求目标类型，例如 `document`、`iframe`、`image`、`script`、`style`，fetch/XHR 为 `empty`；不是 DNR 的 `main_frame` / `sub_frame` 名称 |
| `timestamp` | Unix 毫秒 |
| `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 错误行为时，配置：

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

其他值使用默认行为。按需合并并签名 [EP](https://console.getchrovia.com/zh/docs/sdk-extended-preferences)，然后重启。这只影响错误码，不改变回调决定或超时策略。

## Service Worker 使用注意事项

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

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

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