page.screenshot() 本身是异步方法，但必须在 async 函数中用 await 调用，并确保整个链路处于 async_playwright 上下文内；直接在同步环境调用会报协程未等待错误。
为什么不能直接用 page.screenshot() 异步调用？
Playwright 的异步 API（async + await）要求整个调用链必须在异步上下文中运行，而很多人误以为只要函数名带 async_screenshot 就能用——其实 Playwright 没有这个函数。真实情况是：page.screenshot() 本身在异步上下文里就是异步的，但它必须等待浏览器上下文就绪、页面加载完成、且未被同步阻塞。
常见错误现象：
- 直接在普通函数里写
await page.screenshot(...)→ 报RuntimeWarning: coroutine 'Page.screenshot' was never awaited - 忘记用
async with async_playwright() as p:启动，而是复用同步实例 →AttributeError: 'Playwright' object has no attribute 'chromium'
使用场景：批量截图、定时抓取、配合 FastAPI 异步路由返回图片流。
关键点：所有 Playwright 异步操作必须包裹在 async def 函数内，并由 asyncio.run() 或事件循环驱动；不能混用同步/异步浏览器实例。
立即学习“Python免费学习笔记（深入）”；
如何正确启动异步浏览器并截图？
最简可行代码结构如下，不依赖额外封装：
import asyncio
from playwright.async_api import async_playwright
<p>async def take_screenshot():
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
page = await browser.new_page()
await page.goto("<a href="https://www.php.cn/link/b05edd78c294dcf6d960190bf5bde635">https://www.php.cn/link/b05edd78c294dcf6d960190bf5bde635</a>")
await page.screenshot(path="example.png", full_page=True)
await browser.close()</p><p>asyncio.run(take_screenshot())</p>注意事项：
-
headless=True是默认值，但显式写出更安全（某些 CI 环境需确认） -
full_page=True截长图，否则只截视口区域 -
path必须是字符串路径，不支持Path对象（会静默失败或报TypeError） - 如果截图黑屏，大概率是页面没等加载完就执行了
screenshot()，应加await page.wait_for_load_state("networkidle")
截图时怎么等页面真正“准备好”？
page.goto() 默认只等 load 事件，但 JS 渲染、动态内容、懒加载图片可能还没完成。盲目截图容易截到空白或半成品。
推荐等待策略（按优先级排序）：
-
await page.wait_for_load_state("networkidle")：适合大多数静态+轻量 JS 站点 -
await page.wait_for_function("window.__DATA_LOADED__ === true")：配合前端埋点，最精准 -
await page.wait_for_selector("#main-content", state="visible")：等关键 DOM 元素出现 - 避免
time.sleep()：不可靠，且阻塞异步并发能力
性能影响：过度等待会拖慢吞吐量；过少等待则截图失败率上升。建议先本地调试确定最小稳定等待条件，再上线。
保存为内存字节流而非文件？
有些场景（如 FastAPI 返回 Response(content=..., media_type="image/png")）需要截图结果不落地、直接进内存。
page.screenshot() 支持 type="png" + encoding="binary" 组合返回 bytes：
img_bytes = await page.screenshot(type="png", encoding="binary") # 后续可直接传给 BytesIO 或 HTTP 响应体
注意点：
-
encoding只能是"binary"或"base64"，不能省略或写错 -
type必须与encoding匹配：type="jpeg"时encoding="binary"才有效；type="webp"在某些 Chromium 版本不支持 - 不要同时指定
path和encoding，否则报ValueError: Cannot specify both path and encoding
截图质量受 scale（"css" / "device"）和 quality（仅 JPEG）影响，但异步 API 行为与同步完全一致，无额外限制。
真正容易被忽略的是：Playwright 异步实例不能跨 async with 生命周期复用。每次截图都该新建 page，不要试图缓存 page 对象长期持有——它底层绑定单次导航状态，复用会导致 Target closed 错误。
