跳到主要内容

Playwright for Python：BrowserContext 类中文版文档

BrowserContext（浏览器上下文）是 Playwright 中的核心隔离单元，用于创建独立的浏览器环境。一个 Browser 实例可以包含多个 BrowserContext，每个上下文之间的 Cookie、本地存储（LocalStorage/SessionStorage）、缓存、权限配置等完全隔离，相当于“轻量级浏览器实例”，适用于多账号并行测试、多环境隔离运行等场景。

快速示例​

同步示例​

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    # 启动浏览器
    browser = playwright.chromium.launch(headless=False)
    
    # 创建第一个隔离上下文（账号1）
    context1 = browser.new_context(
        viewport={"width": 1920, "height": 1080},
        user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        locale="zh-CN"
    )
    page1 = context1.new_page()
    page1.goto("https://example.com")
    page1.fill("#username", "user1")
    page1.fill("#password", "123456")
    page1.click("#login")
    print("账号1登录后的Cookie：", context1.cookies())

    # 创建第二个隔离上下文（账号2，与账号1互不干扰）
    context2 = browser.new_context()
    page2 = context2.new_page()
    page2.goto("https://example.com")
    page2.fill("#username", "user2")
    page2.fill("#password", "654321")
    page2.click("#login")
    print("账号2登录后的Cookie：", context2.cookies())

    # 关闭资源
    context1.close()
    context2.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(
        geolocation={"latitude": 39.9042, "longitude": 116.4074},
        permissions=["geolocation", "notifications"]
    )
    page = await context.new_page()
    await page.goto("https://example.com")
    print("上下文当前URL：", page.url)

    # 保存上下文状态（Cookie、本地存储等）
    await context.storage_state(path="storage.json")
    
    # 关闭资源
    await context.close()
    await browser.close()

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

asyncio.run(main())

核心方法​

add_cookies​

向当前上下文添加 Cookie，Cookie 会对该上下文下的所有页面生效。

用法示例​

# 同步
cookies = [
    {
        "name": "auth_token",
        "value": "abc123def456",
        "domain": "example.com",
        "path": "/",
        "expires": 1735689600,  # 过期时间（时间戳）
        "httpOnly": True,
        "secure": True
    }
]
context.add_cookies(cookies)

# 异步
await context.add_cookies(cookies)

参数说明​

  • cookies：Cookie 列表，每个 Cookie 为字典格式，必填字段包括 name、value、domain、path。

add_init_script​

在上下文内所有页面导航或子框架附加时注入初始化脚本，脚本在页面自身脚本执行前运行（全局生效）。

用法示例​

# 同步：通过文件注入
context.add_init_script(path="./global-preload.js")
# 同步：直接注入脚本字符串
context.add_init_script(script="window.customConfig = { env: 'test' };")

# 异步
await context.add_init_script(path="./global-preload.js")
await context.add_init_script(script="window.customConfig = { env: 'test' };")

参数说明​

  • path：JavaScript 文件路径（相对当前工作目录）
  • script：原始 JavaScript 字符串

add_locator_handler​

为上下文内所有页面注册浮层处理逻辑，检测到指定定位器匹配的元素时自动执行处理函数（全局浮层拦截）。

用法示例​

# 同步：全局关闭登录弹窗
def handle_login_modal():
    page = context.pages[0]  # 获取上下文当前活跃页面
    page.get_by_role("button", name="关闭").click()

context.add_locator_handler(
    locator=context.locator("div.login-modal"),
    handler=handle_login_modal,
    times=3  # 最多处理3次
)

# 异步
async def handle_login_modal():
    page = context.pages[0]
    await page.get_by_role("button", name="关闭").click()

await context.add_locator_handler(
    locator=context.locator("div.login-modal"),
    handler=handle_login_modal
)

browser​

获取当前上下文所属的 Browser 实例。

用法​

# 同步
parent_browser = context.browser
print(f"所属浏览器类型：{parent_browser.browser_type.name}")

# 异步
parent_browser = context.browser
print(f"所属浏览器类型：{parent_browser.browser_type.name}")

返回值​

Browser 实例。

clear_cookies​

清空当前上下文的所有 Cookie。

用法​

context.clear_cookies()  # 同步
await context.clear_cookies()  # 异步

clear_permissions​

清空当前上下文的所有已授予权限（如地理位置、通知权限等）。

用法​

context.clear_permissions()  # 同步
await context.clear_permissions()  # 异步

close​

关闭当前浏览器上下文，同时关闭该上下文下的所有 Page 实例。

用法​

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

说明​

  • 关闭后上下文不可再使用，未手动关闭的页面会被自动清理
  • 若为默认上下文，关闭后不会影响 Browser 实例本身

cookies​

获取当前上下文的所有 Cookie，返回 Cookie 列表。

用法​

# 同步
all_cookies = context.cookies()
# 按 URL 筛选 Cookie
filtered_cookies = context.cookies("https://example.com", "https://test.com")
print("当前Cookie：", all_cookies)

# 异步
all_cookies = await context.cookies()
filtered_cookies = await context.cookies("https://example.com")

参数说明​

  • urls（可选）：URL 列表，用于筛选仅对这些 URL 生效的 Cookie。

返回值​

Cookie 列表（每个 Cookie 为字典格式）。

expose_function​

将 Python 函数暴露给浏览器上下文的 JavaScript 环境，可在页面中通过 window.<函数名> 调用。

用法示例​

# 同步：暴露Python函数给JS
def calculate_sum(a, b):
    return a + b

context.expose_function("jsCalculateSum", calculate_sum)
# 在页面中调用
page = context.new_page()
result = page.evaluate("window.jsCalculateSum(10, 20)")
print("JS调用Python函数结果：", result)  # 输出 30

# 异步
async def calculate_sum(a, b):
    return a + b

await context.expose_function("jsCalculateSum", calculate_sum)
page = await context.new_page()
result = await page.evaluate("window.jsCalculateSum(10, 20)")
print("JS调用Python函数结果：", result)

grant_permissions​

为当前上下文授予指定权限，权限对上下文内所有页面生效。

用法示例​

# 同步：授予地理位置和通知权限
context.grant_permissions(
    permissions=["geolocation", "notifications"],
    origin="https://example.com"  # 仅对该域名生效
)

# 异步
await context.grant_permissions(
    permissions=["geolocation"],
    origin="https://example.com"
)

参数说明​

  • permissions：权限列表（支持 geolocation、notifications、camera、microphone 等）
  • origin（可选）：指定权限生效的域名，默认对所有域名生效

new_page​

在当前上下文创建一个新的 Page（标签页），页面继承上下文的所有配置（视口、Cookie、权限等）。

用法​

# 同步
page1 = context.new_page()
page2 = context.new_page()  # 同一上下文下的第二个页面

# 异步
page1 = await context.new_page()
page2 = await context.new_page()

返回值​

Page 实例。

new_browser_cdp_session​

创建上下文级别的 Chrome DevTools Protocol (CDP) 会话，用于对上下文进行底层控制（仅支持 Chromium 内核）。

用法示例​

# 同步
cdp_session = context.new_browser_cdp_session()
cdp_session.send("Network.enable")
# 拦截网络请求
cdp_session.send("Network.setRequestInterception", {"patterns": [{"urlPattern": "*"}]})
cdp_session.detach()

# 异步
cdp_session = await context.new_browser_cdp_session()
await cdp_session.send("Network.enable")
await cdp_session.send("Network.setRequestInterception", {"patterns": [{"urlPattern": "*"}]})
await cdp_session.detach()

说明​

  • 仅适用于 Chromium 浏览器，Firefox/WebKit 不支持
  • 用于实现 Playwright 高层 API 未覆盖的自定义操作

pages​

获取当前上下文下所有活跃的 Page 实例列表。

用法​

# 同步
all_pages = context.pages
print(f"上下文当前有 {len(all_pages)} 个页面")
for page in all_pages:
    print("页面URL：", page.url)

# 异步
all_pages = context.pages
print(f"上下文当前有 {len(all_pages)} 个页面")

返回值​

List[Page]（页面实例列表）。

route​

拦截当前上下文内所有页面的网络请求，支持按 URL 模式匹配并自定义处理逻辑（全局请求拦截）。

用法示例​

# 同步：拦截所有图片请求并返回自定义图片
def handle_image_route(route):
    # 中止图片请求
    route.abort()
    # 或返回自定义响应
    # route.fulfill(
    #     status=200,
    #     content_type="image/png",
    #     body=open("custom-image.png", "rb").read()
    # )

context.route("**/*.{png,jpg,jpeg,gif}", handle_image_route)
page = context.new_page()
page.goto("https://example.com")

# 异步
async def handle_image_route(route):
    await route.abort()

await context.route("**/*.{png,jpg,jpeg,gif}", handle_image_route)
page = await context.new_page()
await page.goto("https://example.com")

set_default_navigation_timeout​

设置当前上下文所有页面的默认导航超时时间（毫秒），覆盖 Playwright 全局默认值（30000 毫秒）。

用法​

# 同步：设置导航超时为10秒
context.set_default_navigation_timeout(10000)

# 异步
await context.set_default_navigation_timeout(10000)

set_default_timeout​

设置当前上下文所有操作的默认超时时间（毫秒），包括元素查找、点击等操作，覆盖全局默认值。

用法​

# 同步：设置默认操作超时为5秒
context.set_default_timeout(5000)

# 异步
await context.set_default_timeout(5000)

set_extra_http_headers​

为当前上下文所有页面的网络请求设置额外的 HTTP 请求头，全局生效。

用法示例​

# 同步
headers = {
    "X-Test-Header": "Playwright-Test",
    "Authorization": "Bearer abc123"
}
context.set_extra_http_headers(headers)

# 异步
await context.set_extra_http_headers(headers)

set_geolocation​

设置当前上下文的地理位置信息，需先授予 geolocation 权限。

用法示例​

# 同步
context.set_geolocation({
    "latitude": 31.2304,
    "longitude": 121.4737,
    "accuracy": 100  # 定位精度（米）
})

# 异步
await context.set_geolocation({
    "latitude": 31.2304,
    "longitude": 121.4737
})

set_locale​

设置当前上下文的语言环境（如 zh-CN、en-US），影响页面的语言渲染和 HTTP 请求头的 Accept-Language。

用法​

# 同步
context.set_locale("zh-CN")

# 异步
await context.set_locale("zh-CN")

set_offline​

切换当前上下文的离线状态，模拟网络断开/恢复场景。

用法示例​

# 同步：开启离线模式
context.set_offline(True)
# 恢复网络连接
context.set_offline(False)

# 异步
await context.set_offline(True)
await context.set_offline(False)

set_storage_state​

加载已保存的存储状态（Cookie、LocalStorage、SessionStorage 等），用于恢复上下文的登录状态等。

用法示例​

# 同步：从文件加载存储状态
context.set_storage_state(path="storage.json")
# 从字典加载存储状态
storage_state = {"cookies": [], "origins": []}
context.set_storage_state(state=storage_state)

# 异步
await context.set_storage_state(path="storage.json")
await context.set_storage_state(state=storage_state)

storage_state​

获取当前上下文的存储状态（Cookie、LocalStorage、SessionStorage 等），可保存为文件或字典用于后续恢复。

用法示例​

# 同步：保存到文件
context.storage_state(path="storage.json")
# 获取存储状态字典
storage_state = context.storage_state()

# 异步
await context.storage_state(path="storage.json")
storage_state = await context.storage_state()

unroute​

移除之前通过 route 注册的请求拦截规则，停止拦截指定模式的网络请求。

用法​

# 同步
context.unroute("**/*.{png,jpg,jpeg}")
# 移除指定处理函数的拦截规则
context.unroute("**/*.png", handle_image_route)

# 异步
await context.unroute("**/*.{png,jpg,jpeg}")
await context.unroute("**/*.png", handle_image_route)

wait_for_event​

等待上下文触发指定事件，并返回事件相关数据，支持超时配置。

用法示例​

# 同步：等待新页面创建
new_page = context.wait_for_event("page", timeout=10000)
print("新页面URL：", new_page.url)

# 异步
new_page = await context.wait_for_event("page", timeout=10000)
print("新页面URL：", new_page.url)

核心属性​

属性用途返回类型说明
browser获取所属浏览器实例Browser所有版本支持
is_closed检查上下文是否已关闭bool所有版本支持
pages获取当前活跃页面列表List[Page]所有版本支持
viewport_size获取/设置上下文默认视口大小Dict（width/height）可直接赋值修改，如 context.viewport_size = {"width": 1280, "height": 720}

常用事件​

事件触发时机事件数据说明
close上下文被关闭时BrowserContext关闭后触发
page上下文内创建新页面时Page包括 new_page() 或页面跳转打开的新页面
request上下文内页面发起网络请求时Request全局请求事件
response上下文内页面收到网络响应时Response全局响应事件
route网络请求匹配 route 拦截规则时Route用于自定义请求处理
download上下文内页面开始下载文件时Download全局下载事件
dialog上下文内页面弹出对话框时（alert/confirm 等）Dialog全局弹窗事件

重要说明​

  1. 隔离性核心：BrowserContext 是 Playwright 实现环境隔离的核心，不同上下文之间无任何状态共享，适合多账号并行测试、多场景隔离验证。
  2. 状态复用：通过 storage_state() 保存登录状态，set_storage_state() 恢复状态，可跳过重复登录流程，提升测试效率。
  3. 全局配置：上下文级别的配置（如超时时间、HTTP 头、权限）会继承给所有子页面，无需在每个页面单独配置。
  4. 资源优化：相比启动多个 Browser 实例，创建多个 BrowserContext 更节省系统资源，是多环境测试的首选方案。
  5. 默认上下文：若直接通过 browser.new_page() 创建页面，Playwright 会自动创建默认上下文，可通过 browser.context 获取。

要不要我帮你整理 BrowserContext 实战场景模板，包含多账号并行测试、登录状态复用、全局请求拦截等可直接运行的代码示例？