Puppeteer

Puppeteer 是 Google 开发的开源 Node.js 库，提供高级 API 来控制 Chrome 和 Firefox，常用于自动截图、测试和网页抓取。

Puppeteer 可以做什么

Puppeteer 通过 Chrome DevTools Protocol 和 WebDriver BiDi 控制受支持的浏览器。它的 API 可以完成大多数人工浏览器操作，以及自动化专用任务。

主要功能包括：

• 页面导航——打开任意 URL，等待特定网络条件或 DOM 元素，并处理重定向和身份验证。
• 截取屏幕截图——渲染页面并保存为 PNG、JPEG 或 WebP，可以截取当前可见视口或整个可滚动页面。
• 生成 PDF——把渲染后的页面导出为 PDF，可以设置页面大小、页边距和页眉/页脚。
• DOM 交互——点击元素、填写表单、选择下拉项和输入文字，适合自动执行截图前需要用户操作的流程。
• 拦截网络请求——监测、修改或阻止网络请求，用于测试错误状态、屏蔽广告或测量资源大小。
• 执行 JavaScript——在页面上下文中运行任意 JavaScript，提取数据，并在截图前修改 DOM。

Puppeteer 控制的是真实浏览器引擎，因此渲染结果与用户在 Chrome 中看到的画面一致，包括 CSS 布局、网页字体、动画和由 JavaScript 驱动的内容。

使用 Puppeteer 截图

截图是 Puppeteer 最常见的用途之一。page.screenshot() 方法提供精确控制：

你可以设置视口尺寸和设备缩放系数，模拟从手机到 4K 显示器的各种屏幕。fullPage 选项会截取整个可滚动文档，而不只是当前可见区域；clip 区域则可用于截取页面中的特定矩形。

对于延迟加载内容，Puppeteer 脚本可以先滚动页面，触发所有延迟图片，再进行截图。还可以通过代码关闭 Cookie 横幅和弹窗，并注入自定义 CSS 隐藏不希望出现在截图中的元素。

截图工具和 API 经常在底层使用 Puppeteer 或类似库，把这些能力封装成更简单的界面，让用户无需编写浏览器自动化脚本也能截取页面。

实际使用中，如果目标是让浏览器自动完成截图，Puppeteer 往往能很快搭好可运行的脚本。以 Chrome 为主的任务可以在一处设置视口、等待逻辑和输出格式，再把同一脚本重复用于检查、报告或定时截图。

Puppeteer 与 Playwright

Puppeteer 和 Playwright 是两种主流无头浏览器自动化库，而且关系密切：Playwright 团队中有多名成员曾参与 Puppeteer 的开发。

浏览器支持是最主要的区别。当前 Puppeteer 版本支持 Chrome for Testing 和稳定版 Firefox。Playwright 通过统一 API 支持 Chromium、Firefox 和 WebKit，因此还能进行 WebKit 截图与测试。

API 设计相似，但 Playwright 还提供一些额外功能，包括内置自动等待（减少明确的等待调用）、用于隔离会话的浏览器上下文，以及对多个页面和 frame 的原生支持。

性能在大多数任务中接近。Puppeteer 直接集成 DevTools Protocol，在仅使用 Chrome 的流程中略有优势；Playwright 的跨浏览器抽象只会增加少量开销。

社区与生态方面，Puppeteer 推出更早，插件和教程更多。Playwright 发展很快，需要跨浏览器支持的新项目通常更倾向于选择它。

常见错误

• 没有等待页面内容。 page.goto() 后立即调用 page.screenshot()，经常会截到不完整页面。应使用 waitUntil: 'networkidle0'，或等待特定选择器，确认内容已经渲染。
• 沿用默认视口尺寸。 Puppeteer 默认视口为 800 × 600，与大多数真实屏幕不符。应明确设置视口尺寸和设备缩放系数，得到准确的高分辨率截图。
• 忽略 Cookie 同意横幅。 自动截图会像首次访问的用户一样打开页面。如果不关闭同意浮层，截图只会显示横幅，而不是页面内容。
• 在服务器上使用有头模式。 Puppeteer 默认使用无头模式；但如果脚本明确启用了有头模式，在没有显示器的服务器上就会失败。服务器和 CI 部署应确认已开启无头模式。
• 没有处理导航错误。 页面可能超时、返回错误或意外重定向。应对导航和截图调用进行错误处理，避免单个页面失败导致整个脚本崩溃。