诊断与异常处理

返回目录

本节说明应用运行时如何取得状态和保存诊断文件。诊断采集默认关闭，由调用者主动开始。

读取 Context 状态

context.diagnostics() -> dict；异步入口使用 await。

Context 已关闭或浏览器意外断开时，仍可返回已有摘要，但不包含新的指纹和代理查询结果。

导航错误项有 kind、at（Unix 毫秒）、origin；navigation_network_error 附 network_error，navigation_http_error 附 http_status。origin 去除 URL 的账号密码、路径、query 和 fragment。

开始采集

context.start_diagnostics(
    include_messages=False,
    max_events=100,
    trace=True,
    runtime_events=True,
)

start_diagnostics(*, include_messages=False, max_events=100, trace=False, runtime_events=True) -> None；异步入口使用 await。

runtime_events=True 会对页面启用 Runtime 事件。设为 False 使用原生 Patchright 事件，其 console/pageerror 在部分运行方式下可能不完整。默认只在明确调用本方法后启用诊断。

采集期间重复开始会抛 DIAGNOSTICS_ACTIVE。已有页面和随后经 SDK 创建的页面会附加采集；原生弹窗在完成附加前的早期事件可能遗漏。该接口不保证覆盖所有 worker 或跨进程 frame 的 console。

保存诊断文件

report = context.capture_diagnostics(
    "diagnostics", page=page, screenshot=True, full_page=False,
    stop_trace=True, max_pages=5, timeout_ms=5000,
)
print(report["report_path"])
context.stop_diagnostics()

capture_diagnostics(directory, *, page=None, screenshot=True, full_page=False, stop_trace=True, max_pages=5, timeout_ms=5000) -> dict；异步入口使用 await。

无需提前 start_diagnostics() 也能取得当前状态与截图，但不会有之前的事件或 trace。要保存 trace，必须先 start_diagnostics(trace=True)，再 capture，最后 stop。stop_trace=False 继续录制，本次不生成 trace 文件。

返回字段

pages 每项包含 origin: str、closed: bool、screenshot: str | None；失败时额外有 screenshot_error: str。截图文件名相对子目录，例如 page-1.png。

page_events 每项包含 kind（如 console、page_error、page_crash）、at（Unix 毫秒）、origin，console 可带 level；只有允许正文且存在文字时才带 message。

单页截图或状态查询失败时尽量返回其他结果，在相应字段记录失败；目录不可写等文件系统错误仍可能直接抛出。此方法不会重试页面业务操作，也不会停止事件收集。

stop_diagnostics() -> None 解除采集，异步入口使用 await。尚未 capture 的 SDK trace 会被丢弃。不要同时用 context.raw.tracing 管理同一段 SDK trace。

诊断元数据不自动导出登录状态、Cookie 文件、启动参数或完整 HTML 文件。截图、trace 内的页面/网络内容以及开启的 message 正文仍可能含业务数据；include_messages=False 不会对图片和 trace 做内容脱敏。

异常类型

from ysbrowser_sdk.sync_api import (
    SDKError, ConfigurationError, CompatibilityError,
    FingerprintLockedError, ProxyCheckError,
)
from patchright.sync_api import Error as BrowserError, TimeoutError as BrowserTimeoutError

try:
    page.goto("https://app.example.com", timeout=15000)
except BrowserTimeoutError as exc:
    print("页面操作超时：", str(exc))
except BrowserError as exc:
    print("页面操作失败：", str(exc))
except SDKError as exc:
    print(exc.to_dict())

URL 为占位地址；将 try 内替换为自己的 SDK 或页面操作。异步程序从 patchright.async_api 导入原生异常，并对异步操作使用 await。

SDKError(code, stage, message, *, context_id=None, details=None, original_error=None) 可用于应用自己的错误包装。四个子类中，ConfigurationError(message) 固定 code="INVALID_CONFIG"、stage="validate"；其余三类沿用基类构造参数。

to_dict() -> dict 返回 code、stage、message、context_id、details，不含 original_error。

原生 Page/Locator 方法抛 Patchright Error / TimeoutError；鼠标模型还会抛 ValueError、RuntimeError、NotImplementedError 等。仅捕获 SDKError 不能涵盖所有页面和模型异常。

错误码与处理

代理切换还可能透传浏览器返回的其他 PROXY_* 操作错误码；读取 code、stage 和 details，并重新查询状态，不假定错误后必然已应用新代理。