Playwright for Python：Browser 类中文版文档

Browser 类对应浏览器实例（如 Chromium、Firefox、WebKit），用于管理浏览器生命周期、创建浏览器上下文（BrowserContext），是 Playwright 浏览器自动化的顶层入口之一。一个 Browser 实例可包含多个独立的 BrowserContext，实现多环境隔离运行。

快速示例

同步示例

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    # 启动 Chromium 浏览器（默认无头模式）
    browser = playwright.chromium.launch(headless=False)
    # 创建浏览器上下文
    context = browser.new_context()
    # 创建页面
    page = context.new_page()
    page.goto("https://example.com")
    print("页面标题：", page.title())
    
    # 关闭资源
    page.close()
    context.close()
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

异步示例

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    # 启动 Firefox 浏览器
    browser = await playwright.firefox.launch()
    # 创建上下文并配置视口
    context = await browser.new_context(viewport={"width": 1280, "height": 720})
    # 打开新页面
    page = await context.new_page()
    await page.goto("https://example.com")
    print("页面 URL：", page.url)
    
    # 关闭资源
    await page.close()
    await context.close()
    await browser.close()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)

asyncio.run(main())

核心方法

browser_type

获取当前浏览器实例对应的浏览器类型（Chromium/Firefox/WebKit）。

用法

# 同步
browser_type = browser.browser_type
print(browser_type.name)  # 输出 "chromium" / "firefox" / "webkit"

# 异步
browser_type = browser.browser_type
print(browser_type.name)

返回值

BrowserType 实例，包含浏览器名称、可执行文件路径等信息。

close

关闭浏览器实例，同时关闭所有关联的 BrowserContext 和 Page。

用法

browser.close()  # 同步
await browser.close()  # 异步

说明

• 关闭后浏览器实例不可再使用，未手动关闭的上下文和页面会被自动清理
• 建议在自动化流程结束时显式调用，避免资源泄露

context

（v1.41+ 新增）获取浏览器的默认上下文（若未手动创建上下文，会自动创建默认上下文）。

用法

# 同步
default_context = browser.context
page = default_context.new_page()  # 使用默认上下文创建页面

# 异步
default_context = browser.context
page = await default_context.new_page()

返回值

BrowserContext 实例（默认上下文）。

is_closed

检查浏览器实例是否已关闭。

用法

# 同步
is_closed = browser.is_closed
print(f"浏览器是否已关闭：{is_closed}")

# 异步
is_closed = browser.is_closed
print(f"浏览器是否已关闭：{is_closed}")

返回值

布尔值（True 表示已关闭，False 表示未关闭）。

new_browser_cdp_session

创建浏览器级别的 Chrome DevTools Protocol (CDP) 会话，用于高级浏览器控制（仅支持 Chromium 内核）。

用法示例

# 同步
cdp_session = browser.new_browser_cdp_session()
# 通过 CDP 启用性能监控
cdp_session.send("Performance.enable")
# 获取性能指标
metrics = cdp_session.send("Performance.getMetrics")
print(metrics)
cdp_session.detach()

# 异步
cdp_session = await browser.new_browser_cdp_session()
await cdp_session.send("Performance.enable")
metrics = await cdp_session.send("Performance.getMetrics")
print(metrics)
await cdp_session.detach()

说明

• 仅适用于 Chromium 浏览器，Firefox/WebKit 不支持 CDP 协议
• 用于执行 Playwright 高层 API 未覆盖的底层操作

new_context

创建新的浏览器上下文（BrowserContext），上下文之间相互隔离（Cookie、本地存储、缓存等互不共享）。

用法示例

# 同步：基础用法
context1 = browser.new_context()

# 同步：带配置的上下文（视口、用户代理、Cookie）
context2 = browser.new_context(
    viewport={"width": 1920, "height": 1080},
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    cookies=[{"name": "token", "value": "123456", "domain": "example.com", "path": "/"}],
    locale="zh-CN",  # 语言环境
    geolocation={"latitude": 39.9042, "longitude": 116.4074}  # 地理位置
)

# 异步
context = await browser.new_context(viewport={"width": 1280, "height": 720})

参数说明（核心参数）

参数	用途	类型
viewport	页面默认视口大小	Dict（width/height）
user_agent	自定义用户代理字符串	str
cookies	初始化 Cookie 列表	List[Dict]
locale	语言环境（如 "zh-CN"、"en-US"）	str
geolocation	地理位置信息	Dict（latitude/longitude）
permissions	授予的权限（如 "geolocation"、"notifications"）	List[str]
headless	是否以无头模式运行上下文	bool
device_scale_factor	设备像素比（如 2 对应高清屏）	int

返回值

BrowserContext 实例。

new_page

直接创建新页面（内部会自动创建默认浏览器上下文，若未存在）。

用法

# 同步
page = browser.new_page()
page.goto("https://example.com")

# 异步
page = await browser.new_page()
await page.goto("https://example.com")

说明

• 便捷用法，适用于简单场景（无需多上下文隔离）
• 若需自定义上下文配置，建议先调用 new_context() 再创建页面

start_tracing

启动浏览器性能追踪，用于记录页面加载、脚本执行等性能数据（仅支持 Chromium）。

用法示例

# 同步
# 启动追踪，保存到文件
browser.start_tracing(path="trace.json", screenshots=True, categories=["devtools.timeline"])
# 执行需要追踪的操作
page = browser.new_page()
page.goto("https://example.com")
# 停止追踪
browser.stop_tracing()

# 异步
await browser.start_tracing(path="trace.json", screenshots=True)
page = await browser.new_page()
await page.goto("https://example.com")
await browser.stop_tracing()

参数说明

• path：追踪数据保存路径（.json 格式）
• screenshots：是否捕获追踪过程中的截图（默认 False）
• categories：指定追踪的性能类别（默认使用预设核心类别）
• snapshots：是否捕获 DOM 快照（默认 False，v1.33+）

stop_tracing

停止浏览器性能追踪，若启动时指定了 path，会自动将追踪数据写入文件。

用法

# 同步
browser.stop_tracing()
# 若未指定 path，可获取追踪数据
trace_data = browser.stop_tracing()

# 异步
await browser.stop_tracing()
trace_data = await browser.stop_tracing()

返回值

若启动追踪时未指定 path，返回追踪数据（二进制格式）；否则返回 None。

version

获取浏览器的版本信息。

用法

# 同步
version = browser.version
print(f"浏览器版本：{version}")  # 示例输出："Chromium 120.0.6099.109"

# 异步
version = browser.version
print(f"浏览器版本：{version}")

返回值

字符串类型，包含浏览器名称和具体版本号。

核心属性

属性	用途	返回类型	适用版本
browser_type	获取浏览器类型（Chromium/Firefox/WebKit）	BrowserType	所有版本
context	获取默认浏览器上下文	BrowserContext	v1.41+
is_closed	检查浏览器是否已关闭	bool	所有版本
version	获取浏览器版本信息	str	所有版本

常用事件

事件	触发时机	事件数据	说明
disconnected	浏览器实例断开连接时（如崩溃、手动关闭）	无	断开后浏览器不可再使用
page	浏览器中创建新页面时	Page	包括通过 new_page() 或页面内跳转打开的新页面
targetchanged	浏览器目标（页面/上下文）发生变化时	Target	仅支持 Chromium 内核
targetcreated	浏览器创建新目标时	Target	仅支持 Chromium 内核
targetdestroyed	浏览器销毁目标时	Target	仅支持 Chromium 内核

重要说明

1. 浏览器启动模式：launch() 默认以无头模式启动，设置 headless=False 可显示浏览器窗口（便于调试）。
2. 资源隔离：不同 BrowserContext 之间的 Cookie、LocalStorage、会话信息完全隔离，适合多账号并行测试。
3. 浏览器兼容性：
   • Chromium：支持 CDP 协议、性能追踪等高级功能
   • Firefox/WebKit：部分底层 API（如 new_browser_cdp_session）不支持
4. 资源释放：建议通过 with 语句（同步）/ async with 语句（异步）管理 Playwright 实例，自动释放资源，避免手动关闭遗漏。

---