Skip to main content
Version: 22.6.1

常见问题

¥FAQ

问：谁维护 Puppeteer？​

¥Q: Who maintains Puppeteer?

Chrome 浏览器自动化团队负责维护该库，但我们希望你能在该项目上提供帮助和专业知识！看看我们的 贡献指南。

¥The Chrome Browser Automation team maintains the library, but we'd love your help and expertise on the project! See our contributing guide.

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

¥Q: What is the status of cross-browser support?

Firefox 官方支持目前处于实验阶段。与 Mozilla 的持续合作旨在支持常见的端到端测试用例，开发者期望跨浏览器覆盖。Puppeteer 团队需要用户的意见来稳定 Firefox 支持并让我们注意到缺失的 API。

¥Official Firefox support is currently experimental. The ongoing collaboration with Mozilla aims to support common end-to-end testing use cases, for which developers expect cross-browser coverage. The Puppeteer team needs input from users to stabilize Firefox support and to bring missing APIs to our attention.

从 Puppeteer v2.1.0 开始，你可以指定 puppeteer.launch({product: 'firefox'}) 在 Firefox Nightly 中运行 Puppeteer 脚本，无需任何额外的自定义补丁。虽然 一个较旧的实验 需要 Firefox 的补丁版本，但 目前的方法 可以使用“普通”Firefox。

¥From Puppeteer v2.1.0 onwards you can specify puppeteer.launch({product: 'firefox'}) to run your Puppeteer scripts in Firefox Nightly, without any additional custom patches. While an older experiment required a patched version of Firefox, the current approach works with “stock” Firefox.

我们将继续与其他浏览器提供者合作，为 Safari 等浏览器提供 Puppeteer 支持。这项工作包括探索执行跨浏览器命令的标准（而不是依赖 Chrome 使用的非标准 DevTools 协议）。

¥We will continue to collaborate with other browser vendors to bring Puppeteer support to browsers such as Safari. This effort includes exploration of a standard for executing cross-browser commands (instead of relying on the non-standard DevTools Protocol used by Chrome).

2023 年 11 月 17 日更新：Puppeteer 对新的 WebDriverBiDi 协议提供实验性支持，可用于自动化 Firefox。Firefox 中的 WebDriver BiDi 实现将来将取代 Firefox 中当前的 CDP 实现。详细信息请参见 https://pptr.nodejs.cn/webdriver-bidi。

¥Update 2023-11-17: Puppeteer has experimental support for the new WebDriverBiDi protocol that can be used to automate Firefox. The WebDriver BiDi implementation in Firefox will replace the current CDP implementation in Firefox in the future. See https://pptr.nodejs.cn/webdriver-bidi for more details.

问：Puppeteer 支持 WebDriver BiDi 吗？​

¥Q: Does Puppeteer support WebDriver BiDi?

Puppeteer 对 WebDriver BiDi 提供了实验性支持。参见 https://pptr.nodejs.cn/webdriver-bidi。

¥Puppeteer has experimental support for WebDriver BiDi. See https://pptr.nodejs.cn/webdriver-bidi.

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

¥Q: What are Puppeteer’s goals and principles?

该项目的目标是：

¥The goals of the project are:

  • 提供高亮 Chrome 开发工具 和 WebDriver 双向 协议功能的参考实现。

    ¥Provide a reference implementation that highlights the capabilities of the Chrome DevTools and WebDriver BiDi protocols.

  • 扩大自动化跨浏览器测试的采用。

    ¥Grow the adoption of automated cross-browser testing.

  • 帮助测试新的 DevTools 协议和 WebDriver BiDi 功能...并捕获错误！

    ¥Help dogfood new DevTools Protocol and WebDriver BiDi features...and catch bugs!

  • 详细了解自动化浏览器测试的痛点并帮助填补这些空白。

    ¥Learn more about the pain points of automated browser testing and help fill those gaps.

我们采用 Chromium 原理 来帮助我们推动产品决策：

¥We adapt Chromium principles to help us drive product decisions:

  • 速度：Puppeteer 相对于自动化页面的性能开销几乎为零。

    ¥Speed: Puppeteer has almost zero performance overhead over an automated page.

  • 安全：Puppeteer 相对于浏览器而言是在进程外运行的，因此可以安全地自动执行潜在的恶意页面。

    ¥Security: Puppeteer operates off-process with respect to the browser, making it safe to automate potentially malicious pages.

  • 稳定：Puppeteer 不应该是不稳定的，也不应该泄漏内存。

    ¥Stability: Puppeteer should not be flaky and should not leak memory.

  • 简单：Puppeteer 提供了易于使用、理解和调试的高级 API。

    ¥Simplicity: Puppeteer provides a high-level API that’s easy to use, understand, and debug.

问：Puppeteer 是 Selenium WebDriver 的替代品吗？​

¥Q: Is Puppeteer a replacement for Selenium WebDriver?

不。这两个项目都具有不同的价值：

¥No. Both projects are valuable for very different reasons:

  • Selenium WebDriver 专注于跨浏览器自动化，并提供多种语言的绑定；Puppeteer 仅适用于 JavaScript。

    ¥Selenium WebDriver focuses on cross-browser automation and provides bindings for multiple languages; Puppeteer is only for JavaScript.

  • Puppeteer 专注于 Chromium；其价值主张是为基于 Chromium 的浏览器提供更丰富的功能。

    ¥Puppeteer focuses on Chromium; its value proposition is richer functionality for Chromium-based browsers.

也就是说，你可以使用 Puppeteer 针对 Chromium 运行测试，例如 使用社区驱动的 jest-puppeteer 或 Puppeteer 的 Angular 集成。虽然这可能不应该是你唯一的测试解决方案，但与经典 WebDriver 相比，它确实有一些优点：

¥That said, you can use Puppeteer to run tests against Chromium, e.g. using the community-driven jest-puppeteer or Puppeteer's Angular integration. While this probably shouldn’t be your only testing solution, it does have a few good points compared to WebDriver classic:

  • Puppeteer 需要零设置，并与最适合它的 Chrome 版本打包在一起，使其成为 很容易上手。

    ¥Puppeteer requires zero setup and comes bundled with the Chrome version it works best with, making it very easy to start with.

  • Puppeteer 具有事件驱动的架构，消除了许多潜在的不稳定因素。在 puppeteer 脚本中不需要“sleep(1000)”调用。

    ¥Puppeteer has event-driven architecture, which removes a lot of potential flakiness. There’s no need for “sleep(1000)” calls in puppeteer scripts.

  • Puppeteer 公开浏览器上下文，从而可以有效地并行测试执行。

    ¥Puppeteer exposes browser contexts, making it possible to efficiently parallelize test execution.

  • Puppeteer 在调试方面表现出色：将“headless”位翻转为 false，添加“slowMo”，你将看到浏览器正在做什么。你甚至可以打开 Chrome DevTools 来检查测试环境。

    ¥Puppeteer shines when it comes to debugging: flip the “headless” bit to false, add “slowMo”, and you’ll see what the browser is doing. You can even open Chrome DevTools to inspect the test environment.

问：为什么 Puppeteer v.XXX 不能与 Chromium v.YYY 配合使用？​

¥Q: Why doesn’t Puppeteer v.XXX work with Chromium v.YYY?

我们将 Puppeteer 视为与 Chromium 不可分割的实体。Puppeteer 的每个版本都打包了特定版本的 Chromium - 这是保证可以使用的唯一版本。

¥We see Puppeteer as an indivisible entity with Chromium. Each version of Puppeteer bundles a specific version of Chromium – the only version it is guaranteed to work with.

这不是人为的限制：Puppeteer 的大量工作实际上是在 Chromium 存储库中进行的。这是一个典型的故事：

¥This is not an artificial constraint: A lot of work on Puppeteer is actually taking place in the Chromium repository. Here’s a typical story:

问：Puppeteer 使用哪个 Chrome 版本？​

¥Q: Which Chrome version does Puppeteer use?

在 revisions.ts 中查找 chrome 条目。

¥Look for the chrome entry in revisions.ts.

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

¥Q: Which Firefox version does Puppeteer use?

由于 Firefox 支持处于实验阶段，因此当 PUPPETEER_PRODUCT 环境变量设置为 firefox 时，Puppeteer 会下载最新的 火狐每晚。这也是 revisions.ts 中 firefox 的值是 latest 的原因 - Puppeteer 不与特定的 Firefox 版本绑定。

¥Since Firefox support is experimental, Puppeteer downloads the latest Firefox Nightly when the PUPPETEER_PRODUCT environment variable is set to firefox. That's also why the value of firefox in revisions.ts is latest -- Puppeteer isn't tied to a particular Firefox version.

要在 Puppeteer 安装过程中获取 Firefox Nightly：

¥To fetch Firefox Nightly as part of Puppeteer installation:

PUPPETEER_PRODUCT=firefox npm i puppeteer

要将 Firefox Nightly 下载到现有的 Puppeteer 项目中：

¥To download Firefox Nightly into an existing Puppeteer project:

npx puppeteer browsers install firefox

问：什么是“导航”？​

¥Q: What’s considered a “Navigation”?

从 Puppeteer 的角度来看，“导航”是指任何更改页面 URL 的内容。除了浏览器访问网络以从 Web 服务器获取新文档的常规导航之外，这还包括 锚点导航 和 历史 API 的使用。

¥From Puppeteer’s standpoint, “navigation” is anything that changes a page’s URL. Aside from regular navigation where the browser hits the network to fetch a new document from the web server, this includes anchor navigations and History API usage.

根据“导航”的定义，Puppeteer 可以与单页应用无缝协作。

¥With this definition of “navigation,” Puppeteer works seamlessly with single-page applications.

问：“trusted"and"untrusted”输入事件有什么区别？​

¥Q: What’s the difference between a “trusted" and "untrusted" input event?

在浏览器中，输入事件可以分为两大组：可信与不可信。

¥In browsers, input events could be divided into two big groups: trusted vs. untrusted.

  • 可信事件：用户与页面交互生成的事件，例如 使用鼠标或键盘。

    ¥Trusted events: events generated by users interacting with the page, e.g. using a mouse or keyboard.

  • 不受信任的事件：由 Web API 生成的事件，例如 document.createEvent 或 element.click() 方法。

    ¥Untrusted event: events generated by Web APIs, e.g. document.createEvent or element.click() methods.

网站可以区分这两组：

¥Websites can distinguish between these two groups:

  • 使用 Event.isTrusted 事件标志

    ¥using an Event.isTrusted event flag

  • 嗅探伴随事件。例如，每个可信 'click' 事件之前都有 'mousedown' 和 'mouseup' 事件。

    ¥sniffing for accompanying events. For example, every trusted 'click' event is preceded by 'mousedown' and 'mouseup' events.

出于自动化目的，生成可信事件非常重要。使用 Puppeteer 生成的所有输入事件都是受信任的，并会触发适当的伴随事件。如果由于某种原因需要一个不受信任的事件，那么总是可以跳到 page.evaluate 的页面上下文并生成一个假事件：

¥For automation purposes it’s important to generate trusted events. All input events generated with Puppeteer are trusted and fire proper accompanying events. If, for some reason, one needs an untrusted event, it’s always possible to hop into a page context with page.evaluate and generate a fake event:

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

问：Puppeteer 支持媒体和音频播放吗？​

¥Q: Does Puppeteer support media and audio playback?

Puppeteer 默认使用 用于测试的 Chrome 二进制文件，从 M120 开始附带专有编解码器支持。

¥Puppeteer uses Chrome for Testing binaries by default which ship with properietary codecs support starting from M120.

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

¥Q: I am having trouble installing / running Puppeteer in my test environment. Where should I look for help?

我们有针对各种操作系统的 troubleshooting 指南，其中列出了所需的依赖。

¥We have a troubleshooting guide for various operating systems that lists the required dependencies.

问：我还有更多问题！我该去哪里询问呢？​

¥Q: I have more questions! Where do I ask?

有多种方法可以获取有关 Puppeteer 的帮助：

¥There are many ways to get help on Puppeteer:

在发布你的问题之前，请务必搜索这些渠道。

¥Make sure to search these channels before posting your question.