本文介绍如何在 python 中借助 pyppeteer 可靠地捕获已完全加载的网页截图，重点解决因异步资源未就绪导致的截图不全问题，推荐使用 `networkidle0` 或 `networkidle2` 等智能等待策略替代固定延时或 dom 就绪判断。
在批量自动化截图场景（如监控、SEO 分析或内容归档）中，仅依赖 load 或 domcontentloaded 事件往往不够——现代网页大量使用异步加载（如 React/Vue 动态组件、懒加载图片、第三方分析脚本、广告 SDK 等），这些资源不会阻塞主文档加载，却直接影响页面视觉完整性。你遇到的“截图不全”问题，本质上是截图时机早于关键资源（如 JS 渲染后的内容、字体、Canvas 图形或 iframe）完成加载。
Pyppeteer 提供了比简单超时更健壮的等待机制：networkidle0 和 networkidle2。它们基于网络活动状态判断页面是否真正“空闲”：
- networkidle0：等待 连续 500ms 内无任何网络请求（最严格，适合静态内容为主或对完整性要求极高的场景）；
- networkidle2：等待 连续 500ms 内活跃网络连接数 ≤ 2（更实用，可容忍少量后台心跳或埋点请求，推荐作为默认选择）。
✅ 正确用法示例（完整可运行脚本）：
import asyncio
from pyppeteer import launch
async def take_full_screenshot(url: str, output_path: str, timeout: int = 60000) -> None:
browser = await launch(headless=True, args=['--no-sandbox', '--disable-setuid-sandbox'])
page = await browser.newPage()
# 设置全局超时（防止无限等待）
await page.setDefaultTimeout(timeout)
try:
# 关键：使用 networkidle2 确保核心资源加载完毕
await page.goto(url, {'waitUntil': 'networkidle2', 'timeout': timeout})
# 可选：等待特定元素确保 JS 渲染完成（如首屏关键区块）
# await page.waitForSelector('main', {'timeout': 10000})
# 截图（支持 fullPage=True 截取整页）
await page.screenshot({'path': output_path, 'fullPage': True})
print(f"✅ Screenshot saved: {output_path}")
except Exception as e:
print(f"❌ Failed to screenshot {url}: {e}")
finally:
await browser.close()
# 批量处理示例（500+ URL 场景需注意并发控制）
async def batch_screenshot(urls: list):
# 建议限制并发数（如 5~10），避免资源耗尽或被风控
semaphore = asyncio.Semaphore(8)
async def bounded_screenshot(url, idx):
async with semaphore:
await take_full_screenshot(url, f"screenshots/{idx:04d}.png")
tasks = [bounded_screenshot(url, i) for i, url in enumerate(urls)]
await asyncio.gather(*tasks)
# 使用方式
if __name__ == "__main__":
urls = ["https://example.com", "https://httpbin.org/html"]
asyncio.run(batch_screenshot(urls))⚠️ 注意事项：
- 避免 await asyncio.sleep()：硬编码延时不可靠（网速/服务器响应波动大），且严重拖慢批量任务；
- 慎用 page.waitForXPath / waitForSelector：若目标元素由 JS 动态插入且无稳定标识，易失败；应优先用 networkidle* + 必要时补充 waitForFunction 检查 JS 状态（如 window.__REACT_READY__ === true）；
- Headless 模式兼容性：部分网站检测无头浏览器并拦截，可添加 userAgent 和 --disable-blink-features=AutomationControlled 并隐藏 WebDriver 特征（需额外配置）；
- 内存与稳定性：批量截图时建议复用 browser 实例（而非每个 URL 新启浏览器），并合理设置 semaphore 控制并发，防止 OOM；
- 备选方案：若 networkidle* 仍不稳定（如长轮询页面），可组合 page.waitForFunction 检查 document.readyState === 'complete' && window.performance.getEntriesByType('resource').length > N。
总结：networkidle2 是平衡可靠
性与效率的首选策略，它从网络层语义上定义“页面就绪”，比 DOM 事件或固定延时更贴近真实用户体验。配合合理的异常处理、并发控制和超时设置，即可稳定支撑数百乃至上千 URL 的高质量截图任务。
