Skip to content

Google Puppeteer 文档的中文版本 , 目标版本 1.9.0, 翻译中...

License

Notifications You must be signed in to change notification settings

demopark/puppeteer-docs-Zh-CN

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
 
 
 
 
 
 

Repository files navigation

Puppeteer Linux Build Status Windows Build Status NPM puppeteer package

此项目同步自 GoogleChrome / puppeteer 项目中的 docs.

Puppeteer 是一个 Node 库,它提供了一系列高级 API 来通过 DevTools 协议 控制 headless Chrome 或 Chromium。 它也可以配置为使用完整的(non-headless)Chrome 或 Chromium。

Puppeteer 能做什么?

可以在浏览器中手动完成的大部分事情都可以使用 Puppeteer 完成! 你可以通过这里的几个例子来起步:

  • 生成页面的截图和PDF。
  • 抓取 SPA 并生成预渲染的内容(即“SSR”)。
  • 从网站抓取内容。
  • 自动表单提交,UI测试,键盘输入等。
  • 创建一个最新的自动化测试环境。 使用最新的 JavaScript 和浏览器功能,直接在最新版本的 Chrome 中运行测试。
  • 捕获你网站的 timeline trace,来帮助诊断性能问题。

在线尝试: https://try-puppeteer.appspot.com/

起步

安装

注意:Puppeteer 至少需要 Node v6.4.0,而下面的例子中使用的 async/await,只有 Node v7.6.0 或更高版本支持

要在你的项目中使用 Puppeteer, 运行:

yarn add puppeteer
# 或 "npm i puppeteer"

注意:当你安装 Puppeteer,它会下载最新版本的 Chromium (~71Mb Mac, ~90Mb Linux, ~110Mb Win) 来保证与 API 协同工作。要跳过下载,参考 Environment variables

使用

Puppeteer 对于使用过其他浏览器测试框架的人来说会很熟悉。 你创建一个 Browser 实例,打开页面,然后使用 Puppeteer 的 API 来操作它们。

示例 - 导航到 https://example.com 然后保存屏幕截图为 example.png:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'example.png'});

  await browser.close();
})();

Puppeteer 设定一个初始页面大小为 800px x 600px, 这决定了截图的大小. 页面大小可以用 Page.setViewport() 来自定义。

示例 - 创建一个 PDF.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://news.ycombinator.com', {waitUntil: 'networkidle2'});
  await page.pdf({path: 'hn.pdf', format: 'A4'});

  await browser.close();
})();

参考 Page.pdf() 来获取关于 pdf 的更多内容。

示例 - 评估页面上下文中的脚本

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  // Get the "viewport" of the page, as reported by the page.
  const dimensions = await page.evaluate(() => {
    return {
      width: document.documentElement.clientWidth,
      height: document.documentElement.clientHeight,
      deviceScaleFactor: window.devicePixelRatio
    };
  });

  console.log('Dimensions:', dimensions);

  await browser.close();
})();

请参阅 Page.evaluate() 以获取更多关于 evaluate 和相关方法的信息,如evaluateOnNewDocumentexposeFunction

默认运行时设置

1. 使用 Headless 模式

Puppeteer 在 headless 模式 中运行 Chromium。要运行完整版本的 Chromium, 需在浏览器加载时设置 'headless' 参数:

const browser = await puppeteer.launch({headless: false}); // 默认是 true

2. 运行 Chromium 的捆绑版本

默认情况下,Puppeteer 下载并使用特定版本的 Chromium,以便使它的 API 保证能开箱即用。 要让 Puppeteer 使用不同版本的 Chrome 或 Chromium,则当创建一个 Browser 实例时传入可执行文件的路径:

const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'});

参考 Puppeteer.launch() 获取更多信息。

参考 本文 来了解 Chromium 和 Chrome 之间的区别。 本文 将介绍对于 Linux 用户的一些差异.

3. 创建一个新的用户配置文件

Puppeteer 创建它自己的 Chromium 用户配置文件,并在每次运行时清理它

API 文档

浏览 API 文档示例 来学习更多内容。

调试提示

  1. 关闭 headless 模式 - 有时查看浏览器显示的内容是非常有用的,而不是在 headless 模式下启动。使用 headless:false 启动完整版本的浏览器:

    const browser = await puppeteer.launch({headless: false});
  2. 慢下来 - slowMo 参数可是使 Puppeteer 操作速度减少指定的毫秒数。 这是另一种帮助查看发生了什么的方法。

    const browser = await puppeteer.launch({
      headless: false,
      slowMo: 250 // 放慢了 250ms
    });
  3. 捕获控制台输出 - 您可以侦听 console 事件。在 page.evaluate() 中调试代码时,这也很方便:

    page.on('console', msg => console.log('PAGE LOG:', ...msg.args));
    
    await page.evaluate(() => console.log(`url is ${location.href}`));
  4. 启用详细日志记录 - 所有公共 API 调用和内部协议流将通过 puppeteer 命名空间下的 debug 模块进行记录。

    # 基本的详细记录
    env DEBUG="puppeteer:*" node script.js
    
    # DEBUG 输出可以通过命名空间来启用/禁用
    env DEBUG="puppeteer:*,-puppeteer:protocol" node script.js # 所有协议消息
    env DEBUG="puppeteer:session" node script.js # 协议会话消息(协议消息到目标)
    env DEBUG="puppeteer:mouse,puppeteer:keyboard" node script.js # 只有鼠标和键盘的 API 调用
    
    # 协议流可能相当嘈杂。 这个例子过滤掉所有网络域的消息
    env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'

贡献 Puppeteer

查看 贡献指南 来获得有关 Puppeteer 开发的概述。

FAQ

Q: Puppeteer 使用哪个 Chromium 版本?

package.json 中查看 chromium_revision.

Puppeteer 捆绑 Chromium 来确保它使用的最新功能可用。 随着 DevTools 协议和浏览器的不断改进,Puppeteer 将被更新为依赖于更新版本的 Chromium。

Q: Puppeteer,Selenium / WebDriver 和 PhantomJS 有什么区别?

Selenium / WebDriver是一个完善的跨浏览器API,可用于测试跨浏览器支持。

Puppeteer 仅适用于 Chromium 或 Chrome。 但是,许多团队只使用一个浏览器(例如PhantomJS)进行单元测试。 在非测试用例中,Puppeteer 提供了一个功能强大但简单的API,因为它只针对一个浏览器,使您能够快速开发自动化脚本。

Puppeteer 捆绑了最新版本的 Chromium。

Q: 谁维护 Puppeteer?

Chrome DevTools 团队负责维护该库,然而我们非常乐意在项目中提供帮助和专业知识! 参考 Contributing.

Q: Chrome 团队为什么要打造 Puppeteer?

该项目的目标很简单:

  • 提供一个精简的,规范的库,强调 DevTools 协议 的功能。
  • 为类似的测试库的实现提供参考。 最终,这些其他框架可以采用 Puppeteer 作为其基础层。
  • 越来越多的采用 headless/automated 浏览器测试。
  • 帮助养成新的 DevTools 协议功能...并捕捉错误!
  • 详细了解自动浏览器测试的难点,并帮助填补这些空白。

Q: Puppeteer 与其他 headless Chrome 项目相比如何?

过去几个月,为自动化 headless Chrome 带来了一些新的库。 作为开发 DevTools 协议的团队,我们很高兴看到和支持这个蓬勃发展的生态系统。

我们已经联系了一些这样的项目,看看是否有合作的机会,我们很乐意尽我们所能帮助。

About

Google Puppeteer 文档的中文版本 , 目标版本 1.9.0, 翻译中...

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published