Skip to main content

Route

通过 page.route(url, handler, **kwargs) 或 browser_context.route(url, handler, **kwargs) 配置网络拦截后，可使用 Route 对象处理该路由。更多信息参见 网络拦截。

route.abort(**kwargs)​

Added in: v1.8
  • 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 - 通用失败。
  • returns: <NoneType>#

终止该路由的请求。

route.continue_(**kwargs)​

Added in: v1.8
  • headers <Dict[str, str]> 若设置则覆盖请求头，值会被转成字符串。#
  • method <str> 若设置则改写请求方法（如 GET、POST）。#
  • post_data <str|bytes> 若设置则替换请求体。#
  • url <str> 若设置则改写请求 URL，新 URL 必须与原 URL 保持同一协议。#
  • returns: <NoneType>#

继续请求，可选择性覆盖部分字段。

def handle(route, request):
    headers = {
        **request.headers,
        "foo": "foo-value",  # 设置 foo 头
        "bar": None          # 移除 bar 头
    }
    route.continue_(headers=headers)
page.route("**/*", handle)

route.fallback(**kwargs)​

Added in: v1.23
  • headers <Dict[str, str]> 若设置该参数，将修改请求的 HTTP 头部。头部值会被转换为字符串。#
  • method <str> 若设置该参数，将修改请求方法（例如 GET 或 POST）。#
  • post_data <str|bytes> 若设置该参数，将修改请求的 POST 数据。#
  • url <str> 若设置该参数，将修改请求的 URL。新 URL 必须与原始 URL 使用相同的协议。修改 URL 不会影响路由匹配，所有路由均基于原始请求 URL 进行匹配。#
  • 返回值： <NoneType>#

当多个路由匹配同一个模式时，它们会以与注册顺序相反的顺序执行。这样，最后注册的路由始终可以覆盖之前的所有路由。在下面的示例中，请求会首先由最下方的处理器处理，然后逐级回退到上一个处理器，最终由最先注册的路由中止该请求。

page.route("**/*", lambda route: route.abort())  # Runs last.
page.route("**/*", lambda route: route.fallback())  # Runs second.
page.route("**/*", lambda route: route.fallback())  # Runs first.

注册多个路由在需要为不同类型的请求指定独立处理逻辑时非常有用，例如区分 API 请求与页面资源，或像下面示例中那样区分 GET 请求与 POST 请求。

# Handle GET requests.
def handle_post(route):
    if route.request.method != "GET":
        route.fallback()
        return
  # Handling GET only.
  # ...

# Handle POST requests.
def handle_post(route):
    if route.request.method != "POST":
        route.fallback()
        return
  # Handling POST only.
  # ...

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

也可以在回退到后续处理器的同时修改请求。通过这种方式，中间的路由处理器可以修改请求的 URL、方法、头部以及 POST 数据。

def handle(route, request):
    # override headers
    headers = {
        **request.headers,
        "foo": "foo-value" # set "foo" header
        "bar": None # remove "bar" header
    }
    route.fallback(headers=headers)
}
page.route("**/*", handle)

route.fulfill(**kwargs)​

Added in: v1.8
  • body <str|bytes> 响应正文。#
  • content_type <str> 若设置，相当于写入 Content-Type 响应头。#
  • headers <Dict[str, str]> 响应头，值会转换成字符串。#
  • path <Union[str, pathlib.Path]> 用文件内容响应。若为相对路径，则相对当前工作目录解析，内容类型会根据扩展名推断。#
  • response <APIResponse> 用已有的 APIResponse 来响应，并可使用其他参数覆盖其字段。#
  • status <int> 响应状态码，默认 200。#
  • returns: <NoneType>#

使用自定义响应满足该请求。以下示例将所有请求返回 404：

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"))

route.request​

Added in: v1.8

返回正被路由的 Request 对象。