Puppeteer 中文文档v25.8.0

常见问题

问：谁在维护 Puppeteer？

Chrome 浏览器自动化团队（Chrome Browser Automation team）维护着这个库，但我们非常希望你在项目上提供帮助和专业知识！请参阅我们的贡献指南。

问：跨浏览器支持的现状如何？

从 Puppeteer v23.0.0 起，Puppeteer 同时支持 Chrome 和 Firefox。

要自动化 Chrome，Puppeteer 默认使用 Chrome DevTools 协议（CDP），但也可以使用 WebDriver BiDi 进行自动化，而 WebDriver BiDi 是自动化 Firefox 的默认方式。

要了解 API 支持上的细微差别，请参阅我们的 WebDriver BiDi 指南。

问：Puppeteer 是否支持 WebDriver BiDi？

从 Puppeteer v23.0.0 及更高版本起，Puppeteer 对 WebDriver BiDi 提供了生产级支持，可用于自动化 Chrome 和 Firefox。

问：Puppeteer 会继续支持 CDP 吗？

我们不会停止使用 CDP 自动化 Chrome——尽管 Puppeteer 支持 WebDriver BiDi。这是为了不破坏依赖 CDP 的现有自动化，同时继续支持 Chrome 独有的、未在 WebDriver BiDi 中标准化的自动化用例。

问：Puppeteer 的目标和原则是什么？

项目的目标是：

  • 提供一个参考实现，展示 Chrome DevTools 和 WebDriver BiDi 协议的能力。
  • 推动自动化跨浏览器测试的普及。
  • 帮助试用新的 DevTools 协议和 WebDriver BiDi 特性……并发现 bug！
  • 更深入地了解自动化浏览器测试的痛点，并帮助填补这些空白。

我们借鉴 Chromium 原则 来帮助我们做出产品决策：

  • 速度：Puppeteer 相对自动化页面几乎没有性能开销。
  • 安全：Puppeteer 在浏览器进程之外运行，因此自动化可能恶意的页面也是安全的。
  • 稳定：Puppeteer 不应出现偶发失败，也不应泄漏内存。
  • 简单：Puppeteer 提供了一个易于使用、理解和调试的高级 API。

问：Puppeteer 是 Selenium 的替代品吗？

Puppeteer 是一个基于 Node.js 的参考实现，展示了如何使用 CDP 和 WebDriver BiDi 自动化浏览器——Selenium 项目也正在为这一 Web 标准做贡献。

Selenium 项目在多个方面超出了 Puppeteer 所提供的：它提供的绑定语言不止 JavaScript，例如还提供大规模编排自动化的工具，如 Selenium Grid。这两者都超出了 Puppeteer 的范围。

还有一些社区项目为 Puppeteer 在核心之外添加了能力，使测试等事情更加方便。例如：

问：为什么 Puppeteer v.XXX 与某个特定版本的 Chrome 或 Firefox 不兼容？

每个 Puppeteer 版本都与特定的浏览器版本紧密捆绑，以确保与底层协议（Chrome DevTools 协议和 WebDriver BiDi）的实现保持兼容。

这是为了防止 Chrome 或 Firefox 的任何变化意外破坏 Puppeteer。

问：Puppeteer 使用哪个版本的 Chrome 和 Firefox？

请在 revisions.ts 中查找 chrome 和 firefox 条目。

问：什么算作“导航”？

从 Puppeteer 的角度来看，“导航”指任何会改变页面 URL 的操作。除了浏览器访问网络、从 Web 服务器获取新文档的常规导航之外，这还包括锚点导航和 History API 的使用。

基于“导航”的这个定义，Puppeteer 可以与单页应用无缝协作。

问：“可信”与“不可信”输入事件有什么区别？

在浏览器中，输入事件可以分为两大类：可信（trusted）事件与不可信（untrusted）事件。

  • 可信事件：由用户与页面交互（例如使用鼠标或键盘）产生的事件。
  • 不可信事件：由 Web API（例如 document.createEvent 或 element.click() 方法）产生的事件。

网站可以通过以下方式区分这两类事件：

  • 使用 Event.isTrusted 事件标志
  • 探测伴随事件。例如，每个可信的 'click' 事件之前都会有 'mousedown' 和 'mouseup' 事件。

出于自动化目的，生成可信事件非常重要。Puppeteer 生成的所有输入事件都是可信的，并且会触发正确的伴随事件。 如果出于某种原因需要不可信事件，始终可以通过 page.evaluate 进入页面上下文并生成一个伪造事件：

await page.evaluate(() => {
  document.querySelector('button[type=submit]').click();
});

问：Puppeteer 是否支持媒体和音频播放？

Puppeteer 默认使用 Chrome for Testing 二进制文件，从 M120 起，这些二进制文件附带专有编解码器支持。

问：我在测试环境中安装/运行 Puppeteer 时遇到问题，应该去哪里寻求帮助？

我们有一份面向各种操作系统的故障排查指南，其中列出了所需的依赖。

问：我还有其他问题！应该去哪里提问？

有多种方式可以获得 Puppeteer 的帮助：

发帖提问之前，请务必先在这些渠道中搜索。