跳到主要内容

Playwright for Python：Route 类中文文档

当通过 page.route() 或 browser_context.route() 设置网络路由时，Route 对象可用于处理该路由的请求。本文档详细介绍其方法、属性及使用示例。

一、核心方法​

1. abort() - 终止路由请求​

终止当前路由对应的网络请求，可指定错误码。

使用方式​

route.abort()
route.abort(**kwargs)

参数说明​

  • error_code（str，可选）：错误码，默认值为 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'：通用失败（默认值）

返回值​

NoneType（无返回值）

2. continue_() - 继续路由请求（可选覆盖参数）​

将路由请求发送至网络，支持对请求头、方法、请求体、URL 进行覆盖修改。

使用示例​

同步模式

def handle(route, request):
    # 覆盖请求头：添加 foo 头、删除 bar 头
    headers = {
        **request.headers,
        "foo": "foo-value",
        "bar": None
    }
    route.continue_(headers=headers)

page.route("**/*", handle)

异步模式

async def handle(route, request):
    # 覆盖请求头：添加 foo 头、删除 bar 头
    headers = {
        **request.headers,
        "foo": "foo-value",
        "bar": None
    }
    await route.continue_(headers=headers)

await page.route("**/*", handle)

参数说明​

  • headers（Dict[str, str]，可选）：修改请求的 HTTP 头，值会自动转为字符串
  • method（str，可选）：修改请求方法（如 GET、POST）
  • post_data（str | bytes | Dict，可选）：修改请求的 POST 数据
  • url（str，可选）：修改请求 URL，新 URL 必须与原 URL 协议一致

返回值​

NoneType（无返回值）

注意事项​

  • 头信息（headers）的修改适用于当前路由请求及后续重定向请求；URL、方法（method）、POST 数据仅适用于原始请求，不会传递到重定向请求。
  • 调用后会立即将请求发送至网络，后续匹配的路由处理器不会被触发；若需触发后续处理器，需使用 route.fallback()。
  • 无法通过该方法覆盖 Cookie 头（即使指定也会被忽略，Cookie 从浏览器 Cookie 存储中加载）；如需设置自定义 Cookie，使用 browser_context.add_cookies()。

3. fallback() - fallback 路由请求（触发后续处理器）​

与 continue_() 类似，支持覆盖请求参数，但会先触发后续匹配的路由处理器，再将请求发送至网络。

使用场景​

当多个路由处理器匹配同一请求时，按注册顺序反向执行（最后注册的先执行）。适用于按请求类型（如 API/页面资源、GET/POST）拆分处理器逻辑。

使用示例​

多路由处理器执行顺序

# 同步模式
page.route("**/*", lambda route: route.abort())  # 最后执行（终止请求）
page.route("**/*", lambda route: route.fallback())  # 中间执行（fallback 到下一个处理器）
page.route("**/*", lambda route: route.fallback())  # 最先执行（fallback 到下一个处理器）

# 异步模式
await page.route("**/*", lambda route: route.abort())  # 最后执行
await page.route("**/*", lambda route: route.fallback())  # 中间执行
await page.route("**/*", lambda route: route.fallback())  # 最先执行

按请求方法拆分处理器

# 同步模式
# 处理 GET 请求
def handle_get(route):
    if route.request.method != "GET":
        route.fallback()  # 非 GET 请求，传递给下一个处理器
        return
    # 仅处理 GET 请求的逻辑
    # ...

# 处理 POST 请求
def handle_post(route):
    if route.request.method != "POST":
        route.fallback()  # 非 POST 请求，传递给下一个处理器
        return
    # 仅处理 POST 请求的逻辑
    # ...

page.route("**/*", handle_get)
page.route("**/*", handle_post)

# 异步模式
async def handle_get(route):
    if route.request.method != "GET":
        await route.fallback()
        return
    # 仅处理 GET 请求的逻辑
    # ...

async def handle_post(route):
    if route.request.method != "POST":
        await route.fallback()
        return
    # 仅处理 POST 请求的逻辑
    # ...

await page.route("**/*", handle_get)
await page.route("**/*", handle_post)

fallback 时修改请求参数

# 同步模式
def handle(route, request):
    headers = {
        **request.headers,
        "foo": "foo-value",  # 添加头
        "bar": None  # 删除头
    }
    route.fallback(headers=headers)

page.route("**/*", handle)

# 异步模式
async def handle(route, request):
    headers = {
        **request.headers,
        "foo": "foo-value",
        "bar": None
    }
    await route.fallback(headers=headers)

await page.route("**/*", handle)

参数说明​

与 continue_() 一致：headers、method、post_data、url（新 URL 需与原协议一致，且路由匹配仍基于原始 URL）。

返回值​

NoneType（无返回值）

4. fetch() - 预获取请求结果（不完成请求）​

执行请求并获取响应结果，但不将响应返回给页面，支持修改响应后再通过 fulfill() 完成请求。

使用示例​

# 同步模式
def handle(route):
    response = route.fetch()
    json = response.json()
    json["message"]["big_red_dog"] = []  # 修改响应数据
    route.fulfill(response=response, json=json)  # 用修改后的响应完成请求

page.route("https://dog.ceo/api/breeds/list/all", handle)

# 异步模式
async def handle(route):
    response = await route.fetch()
    json = await response.json()
    json["message"]["big_red_dog"] = []
    await route.fulfill(response=response, json=json)

await page.route("https://dog.ceo/api/breeds/list/all", handle)

参数说明​

  • headers（Dict[str, str]，可选）：修改请求头
  • max_redirects（int，可选，v1.31+）：最大自动跟随重定向次数，默认 20，传 0 不跟随
  • max_retries（int，可选，v1.46+）：网络错误重试次数（仅重试 ECONNRESET 错误），默认 0（不重试）
  • method（str，可选）：修改请求方法
  • post_data（str | bytes | Dict，可选）：设置 POST 数据（对象会序列化为 JSON，默认 content-type 为 application/json；非对象默认 application/octet-stream）
  • timeout（float，可选，v1.33+）：请求超时时间（毫秒），默认 30000（30 秒），传 0 禁用超时
  • url（str，可选）：修改请求 URL（需与原协议一致）

返回值​

APIResponse（请求响应对象）

注意事项​

头信息（headers）的修改适用于当前请求及后续重定向；若仅需修改原始请求头，使用 route.continue_()。

5. fulfill() - 自定义响应完成请求​

用自定义的响应数据（状态码、响应体、头信息等）完成路由请求，无需发送至网络。

使用示例​

返回 404 响应

# 同步模式
page.route("**/*", lambda route: route.fulfill(
    status=404,
    content_type="text/plain",
    body="not found!"
))

# 异步模式
await page.route("**/*", lambda route: route.fulfill(
    status=404,
    content_type="text/plain",
    body="not found!"
))

返回本地文件作为响应

# 同步模式
page.route("**/xhr_endpoint", lambda route: route.fulfill(path="mock_data.json"))

# 异步模式
await page.route("**/xhr_endpoint", lambda route: route.fulfill(path="mock_data.json"))

参数说明​

  • body（str | bytes，可选）：响应体内容
  • content_type（str，可选）：响应的 Content-Type 头（等价于设置 headers 中的 Content-Type）
  • headers（Dict[str, str]，可选）：响应头信息
  • json（Dict，可选，v1.29+）：JSON 格式响应体，默认设置 content-type 为 application/json
  • path（Union[str, pathlib.Path]，可选）：本地文件路径（相对路径基于当前工作目录），会自动根据文件扩展名推断 content-type
  • response（APIResponse，可选，v1.15+）：基于现有响应对象构建新响应，可通过其他参数覆盖部分字段（如头信息）
  • status（int，可选）：响应状态码，默认 200

返回值​

NoneType（无返回值）

二、属性​

request - 获取当前路由的请求对象​

获取路由对应的原始请求信息。

使用方式​

route.request

返回值​

Request（请求对象，包含请求 URL、方法、头信息等详情）