Route

当通过 page.route() 或 browserContext.route() 设置网络路由时，Route 对象可用于处理该路由。

了解更多关于网络的信息。

方法

abort

v1.9 之前添加

route.abort

中止路由请求。

用法

await route.abort();
await route.abort(errorCode);

参数

errorCode string (可选)#

可选错误码。默认为 failed，可以是以下值之一：
- 'aborted' - 操作被中止（由于用户操作）
- 'accessdenied' - 访问资源（非网络资源）的权限被拒绝
- 'addressunreachable' - IP 地址不可达。通常表示没有到指定主机或网络的路由。
- 'blockedbyclient' - 客户端选择阻止该请求。
- 'blockedbyresponse' - 请求失败，因为响应附带的要求未满足（例如 'X-Frame-Options' 和 'Content-Security-Policy' 祖先检查）。
- 'connectionaborted' - 由于未收到发送数据的 ACK 导致连接超时。
- 'connectionclosed' - 连接已关闭（对应 TCP FIN）。
- 'connectionfailed' - 连接尝试失败。
- 'connectionrefused' - 连接尝试被拒绝。
- 'connectionreset' - 连接被重置（对应 TCP RST）。
- 'internetdisconnected' - 互联网连接已断开。
- 'namenotresolved' - 无法解析主机名。
- 'timedout' - 操作超时。
- 'failed' - 发生一般性错误。

返回值

Promise<void>#

continue

在 v1.9 之前添加

route.continue

将路由请求发送到网络，可选择性地覆盖某些参数。

用法

await page.route('**/*', async (route, request) => {
  // 覆盖请求头
  const headers = {
    ...request.headers(),
    foo: 'foo-value', // 设置 "foo" 请求头
    bar: undefined, // 移除 "bar" 请求头
  };
  await route.continue({ headers });
});

参数

options Object (可选)
- headers Object<string, string> (可选)#
  
  如果设置，将修改请求的 HTTP 头。头值会被转换为字符串。
- method string (可选)#
  
  如果设置，将修改请求方法（例如 GET 或 POST）。
- postData string | Buffer | Serializable (可选)#
  
  如果设置，将修改请求的 post 数据。
- url string (可选)#
  
  如果设置，将修改请求 URL。新 URL 必须与原始 URL 使用相同的协议。

Promise<void>#

详情

headers 选项会同时应用于路由请求及其引发的任何重定向。但是 url、method 和 postData 仅适用于原始请求，不会传递给重定向请求。

route.continue() 会立即将请求发送到网络，不会调用其他匹配的处理程序。如果想调用链中的下一个匹配处理程序，请使用 route.fallback()。

注意

无法使用此方法覆盖 Cookie 头。如果提供了值，它将被忽略，cookie 会从浏览器的 cookie 存储中加载。要设置自定义 cookie，请使用 browserContext.addCookies()。

fallback

v1.23 版本新增

route.fallback

使用可选覆盖参数继续路由请求。该方法类似于 route.continue()，区别在于在发送请求前会先调用其他匹配的处理程序。

使用场景

当多个路由匹配给定模式时，它们会按照与注册顺序相反的顺序执行。这样最后注册的路由总是可以覆盖之前的所有路由。在下面的示例中，请求将首先由最底部的处理程序处理，然后回退到前一个处理程序，最终由第一个注册的路由中止。

await page.route('**/*', async route => {
  // 最后执行
  await route.abort();
});
await page.route('**/*', async route => {
  // 第二个执行
  await route.fallback();
});
await page.route('**/*', async route => {
  // 第一个执行
  await route.fallback();
});

当您希望不同的处理程序处理不同类型的请求时（例如 API 调用与页面资源，或 GET 请求与 POST 请求），注册多个路由非常有用，如下例所示。

// 处理 GET 请求
await page.route('**/*', async route => {
  if (route.request().method() !== 'GET') {
    await route.fallback();
    return;
  }
  // 仅处理 GET 请求
  // ...
});

// 处理 POST 请求
await page.route('**/*', async route => {
  if (route.request().method() !== 'POST') {
    await route.fallback();
    return;
  }
  // 仅处理 POST 请求
  // ...
});

也可以在回退到后续处理程序时修改请求，这样中间路由处理程序可以修改请求的 URL、方法、头部和 postData。

await page.route('**/*', async (route, request) => {
  // 覆盖头部
  const headers = {
    ...request.headers(),
    foo: 'foo-value', // 设置 "foo" 头部
    bar: undefined, // 移除 "bar" 头部
  };
  await route.fallback({ headers });
});

使用 route.continue() 可以立即将请求发送到网络，这种情况下不会调用其他匹配的处理程序。

参数

options Object (可选)
- headers Object<string, string> (可选)#
  
  如果设置，将更改请求的 HTTP 头部。头部值将被转换为字符串。
- method string (可选)#
  
  如果设置，将更改请求方法（例如 GET 或 POST）。
- postData string | Buffer | Serializable (可选)#
  
  如果设置，将更改请求的 post 数据。
- url string (可选)#
  
  如果设置，将更改请求 URL。新 URL 必须与原始 URL 使用相同的协议。更改 URL 不会影响路由匹配，所有路由都使用原始请求 URL 进行匹配。

返回值

Promise<void>#

fetch

添加于: v1.29

route.fetch

执行请求并获取结果但不直接完成响应，以便可以修改响应后再完成。

用法

await page.route('https://dog.ceo/api/breeds/list/all', async route => {
  const response = await route.fetch();
  const json = await response.json();
  json.message['big_red_dog'] = [];
  await route.fulfill({ response, json });
});

参数

options Object (可选)
- headers Object<string, string> (可选)#
  
  如果设置，将更改请求的 HTTP 头。头值将被转换为字符串。
- maxRedirects number (可选) 添加于: v1.31#
  
  自动跟随的最大请求重定向次数。如果超过此数字将抛出错误。默认为 20。传递 0 表示不跟随重定向。
- maxRetries number (可选) 添加于: v1.46#
  
  网络错误的最大重试次数。当前仅重试 ECONNRESET 错误。不会基于 HTTP 响应码重试。如果超过限制将抛出错误。默认为 0 - 不重试。
- method string (可选)#
  
  如果设置，将更改请求方法（例如 GET 或 POST）。
- postData string | Buffer | Serializable (可选)#
  
  允许设置请求的 post 数据。如果数据参数是对象，它将被序列化为 json 字符串，并且如果未显式设置，content-type 头将被设置为 application/json。否则，如果未显式设置，content-type 头将被设置为 application/octet-stream。
- timeout number (可选) 添加于: v1.33#
  
  请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示禁用超时。
- url string (可选)#
  
  如果设置，将更改请求 URL。新 URL 必须与原始 URL 使用相同的协议。

返回值

Promise<APIResponse>#

详情

请注意 headers 选项将应用于获取的请求以及由其发起的任何重定向。如果只想将 headers 应用于原始请求而不应用于重定向，请查看 route.continue()。

fulfill

v1.9 版本前添加

route.fulfill

使用给定的响应来满足路由请求。

用法

以下是用 404 响应满足所有请求的示例：

await page.route('**/*', async route => {
  await route.fulfill({
    status: 404,
    contentType: 'text/plain',
    body: 'Not Found!'
  });
});

以下是提供静态文件的示例：

await page.route('**/xhr_endpoint', route => route.fulfill({ path: 'mock_data.json' }));

参数

options Object (可选)
- body string | Buffer (可选)#
  
  响应体。
- contentType string (可选)#
  
  如果设置，等同于设置 Content-Type 响应头。
- headers Object<string, string> (可选)#
  
  响应头。头值将被转换为字符串。
- json Serializable (可选) v1.29 版本新增#
  
  JSON 响应。如果未设置内容类型，此方法会将其设置为 application/json。
- path string (可选)#
  
  用于响应的文件路径。内容类型将从文件扩展名推断。如果 path 是相对路径，则相对于当前工作目录解析。
- response APIResponse (可选) v1.15 版本新增#
  
  用于满足路由请求的 APIResponse。可以使用 fulfill 选项覆盖响应的各个字段（如 headers）。
- status number (可选)#
  
  响应状态码，默认为 200。

Promise<void>#

request

v1.9 之前版本添加

route.request

需要被路由的请求。

用法

route.request();

返回值

Request #

方法​

abort​

continue​

fallback​

fetch​

fulfill​

request​

方法

abort

continue

fallback

fetch

fulfill

request