class: Puppeteer

3.1.0

3.1.0

Puppeteer 模块提供了一种启动 Chromium 实例的方法。
以下是使用 Puppeteer 驱动自动化的典型示例：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com');
  // 其他操作...
  await browser.close();
})();

puppeteer.connect(options)

• options <[Object]>
  • browserWSEndpoint <?[string]> 一个要连接的 browser websocket endpoint。
  • browserURL <?[string]> a browser url to connect to, in format http://${host}:${port}. Use interchangeably with browserWSEndpoint to let Puppeteer fetch it from metadata endpoint.
  • ignoreHTTPSErrors <[boolean]> 在跳转是否忽略HTTPS错误。默认为false。
  • defaultViewport <?[Object]> 为每个页面设置一致的窗口。默认为800 x 600 。null禁用默认窗口 。
  • width <[number]> 页面宽度(以像素为单位)。
  • height <[number]> 页面高度(以像素为单位)。
  • deviceScaleFactor <[number]> 指定设备比例因子(可以认为是 dpr )。默认为1。
  • isMobile <[boolean]> 是否考虑meta viewport标签记入角色(Whether the meta viewport tag is taken into account)。默认为false。
  • hasTouch<[boolean]> 指定视口是否支持触摸事件。默认为false。
  • isLandscape <[boolean]> 指定视口是否处于横向模式。默认为false。
  • slowMo <[number]> 将伪造角色的操作减慢指定的毫秒数。这样您可以查看发生了什么。
  • transport <[ConnectionTransport]> 实验 为Puppeteer指定要使用的自定义传输对象。
  • product <[string]> 可能的值为：chrome，firefox。默认为chrome。
• returns: <[Promise]<[Browser]>>

此方法将 Puppeteer 连接到现有的 Chromium 实例。

puppeteer.createBrowserFetcher([options])

• options <[Object]>
  • host <[string]> A download host to be used. Defaults to https://storage.googleapis.com. If the product is firefox, this defaults to https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central.
  • path <[string]> A path for the downloads folder. Defaults to <root>/.local-chromium, where <root> is puppeteer's package root. If the product is firefox, this defaults to <root>/.local-firefox.
  • platform <"linux"|"mac"|"win32"|"win64"> [string] for the current platform. Possible values are: mac, win32, win64, linux. Defaults to the current platform.
  • product <"chrome"|"firefox"> [string] for the product to run. Possible values are: chrome, firefox. Defaults to chrome.
• returns: <[BrowserFetcher]>

puppeteer.defaultArgs([options])

• options <[Object]> 在浏览器上设置的可配置选项集。可以具有以下字段：
  • headless <[boolean]> 是否以 无头模式 (headless mode)运行浏览器。除非devtools选项为true 时为false，否则默认为true。
  • args <[Array]<[string]>> 传递给浏览器实例的其他参数。可以在这里 找到Chromium标志列表。
  • userDataDir <[string]> 用户数据目录（User Data Directory）的路径。
  • devtools <[boolean]> 是否为每个选项卡自动打开DevTools面板。如果此选项为true，则headless选项会被设置为false。
• returns: <[Array]<[string]>>

Chromium 的默认标志将与之一起启动。

puppeteer.devices

• returns: <[Object]>

返回要与 page.emulate(options)一起使用的设备的列表。可以在 src/DeviceDescriptors.js中找到设备的实际列表。

const puppeteer = require('puppeteer');
const iPhone = puppeteer.devices['iPhone 6'];

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.emulate(iPhone);
  await page.goto('https://www.google.com');
  // 其他操作...
  await browser.close();
})();

注意 旧方法 (Puppeteer versions <= v1.14.0) 中设备可以通过require('puppeteer/DeviceDescriptors')方法获得。

puppeteer.errors

• returns: <[Object]>
  • TimeoutError <[function]> A class of [TimeoutError].
    如果 Puppeteer 方法不能完成一个请求。例如page.waitForSelector(selector[, options])
    如果选择器在给定的时间段内与任何节点都不匹配，则会失败。

对于某些类型的错误，puppeter 使用特定的错误类。
这些类可通过puppeteer.errors使用这些类。

处理超时错误的示例：

try {
  await page.waitForSelector('.foo');
} catch (e) {
  if (e instanceof puppeteer.errors.TimeoutError) {
    // 超时异常处理.
  }
}

注意 旧方法中 (Puppeteer versions <= v1.14.0) 错误可以通过require('puppeteer/Errors')获取。

puppeteer.executablePath()

• returns: <[string]> Puppeteer 会通过该路径找到指定的浏览器。如果使用PUPPETEER_SKIP_DOWNLOAD跳过下载，则浏览器二进制文件可能不存在。

注意 puppeteer.executablePath() 受PUPPETEER_EXECUTABLE_PATH和PUPPETEER_CHROMIUM_REVISION 变量的影响。有关详细信息，详细信息请参见Environment Variables。

puppeteer.launch([options])

• options <[Object]> 在浏览器上设置的可配置选项集。可以具有以下字段：
  • product <[string]> 启动哪个浏览器。目前，这是chrome或firefox。另请参见PUPPETEER_PRODUCT。
  • ignoreHTTPSErrors <[boolean]> 是否忽略HTTPS错误。默认为false。
  • headless <[boolean]> 是否以 无头模式 (headless mode)运行浏览器。除非devtools选项为true 时为false，否则默认为true。
  • executablePath <[string]> 浏览器可执行文件而不是捆绑的 Chromium 的路径。如果executablePath是相对路径，则相对于当前工作目录 (current working directory)进行解析。 警告: Puppeteer 只保证能够工作 于指定的 Chromium下, 使用其他浏览器风险自负.
  • slowMo <[number]> 将伪造角色的操作减慢指定的毫秒数。这样您可以查看发生了什么。
  • defaultViewport <?[Object]> 为每个页面设置一致的窗口。默认为800 x 600 。null禁用默认窗口 。
  • width <[number]> 页面宽度(以像素为单位)。
  • height <[number]> 页面高度(以像素为单位)。
  • deviceScaleFactor <[number]> 指定设备比例因子(可以认为是 dpr )。默认为1。
  • isMobile <[boolean]> 是否考虑meta viewport标签记入角色(Whether the meta viewport tag is taken into account)。默认为false。
  • hasTouch<[boolean]> 指定视口是否支持触摸事件。默认为false。
  • isLandscape <[boolean]> 指定视口是否处于横向模式。默认为false。
  • args <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found here, and here is the list of Firefox flags.
  • ignoreDefaultArgs <[boolean]|[Array]<[string]>> 如果true，则不要使用[puppeteer.defaultArgs()](# puppeteerdefaultargsoptions)。如果给出了数组，则过滤掉给定的默认参数。有风险的选项；请谨慎使用。默认为false。
  • handleSIGINT <[boolean]> 通过 Ctrl-C上关闭浏览器进程。默认为true。
  • handleSIGTERM <[boolean]> 关闭SIGTERM上的浏览器进程。默认为true。
  • handleSIGHUP <[boolean]> 关闭SIGHUP上的浏览器进程。默认为true。
  • timeout <[number]> 等待浏览器实例启动的最长时间(以毫秒为单位)。默认为30000(30秒)。传递0以禁用超时。
  • dumpio <[boolean]> 是否将浏览器进程stdout和stderr通过管道传输到process.stdout和process.stderr中。默认为false。
  • userDataDir <[string]>用户数据目录（User Data Directory）](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md)的路径。
  • env <[Object]> 指定将对浏览器可见的环境变量。默认为process.env。
  • devtools <[boolean]> 是否为每个选项卡自动打开DevTools面板。如果此选项为true，则headless选项会被设置为false。
  • pipe <[boolean]> 通过管道而不是WebSocket连接到浏览器。默认为false。
  • extraPrefsFirefox <[Object]> 可以传递给Firefox的其他 特性 (请查阅 PUPPETEER_PRODUCT)。
• returns: <[Promise]<[Browser]>> Promise which resolves to browser instance.

您可以使用ignoreDefaultArgs从默认参数中过滤出--mute-audio：

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--mute-audio']
});

注意 Puppeteer 也可用于控制 Chrome 浏览器，但与指定的 Chromium版本配合使用效果最佳。无法保证它将与任何其他版本一起使用。使用executablePath 选项时要格外小心。

如果首选Google Chrome(而不是Chromium)，请参阅 Chrome Canary 或 Dev Channel 获取指导。

在上面的 puppeteer.launch([options]) 方法中任何提及 Chromium 也适用于 Chrome 。

请参阅 这篇文章 了解 Chromium 和 Chrome 之间的区别。 这篇文章 描述了 Linux 用户的一些区别。

puppeteer.product

• returns: <[string]> 返回处于自动化状态的浏览器的名称(“ chrome”或“ firefox”)。

product 由PUPPETEER_PRODUCT环境变量或puppeteer.launch([options])中的product选项设置，默认为chrome。 Firefox支持是试验性的。

Puppeteer 模块提供了一种启动 Chromium 实例的方法。
以下是使用 Puppeteer 驱动自动化的典型示例：

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/puppeteer/3.1.0...

译文地址：https://learnku.com/docs/puppeteer/3.1.0...