木偶
指南 | API | 常见问题解答 | 贡献 | 故障排除
木偶是一个 Node.js 库，它提供了一个高级 API 来通过 DevTools 协议 控制 Chrome/Chromium。木偶默认情况下在 无头 模式下运行，但可以配置为在完整的（“有头”）Chrome/Chromium 中运行。
我能做什么？
大多数您可以在浏览器中手动执行的操作都可以使用 Puppeteer 完成！以下是一些入门示例
- 生成网页的屏幕截图和 PDF。
- 爬取 SPA（单页应用程序）并生成预渲染内容（即“SSR”（服务器端渲染））。
- 自动化表单提交、UI 测试、键盘输入等。
- 使用最新的 JavaScript 和浏览器功能创建自动化测试环境。
- 捕获您的网站的 时间线跟踪，以帮助诊断性能问题。
- 测试 Chrome 扩展程序.
入门
安装
要在您的项目中使用 Puppeteer，请运行
npm i puppeteer
# or using yarn
yarn add puppeteer
# or using pnpm
pnpm i puppeteer
安装 Puppeteer 时，它会自动下载最新版本的 Chrome for Testing（约 170MB macOS、约 282MB Linux、约 280MB Windows）和一个 chrome-headless-shell 二进制文件（从 Puppeteer v21.6.0 开始），该文件 保证与 Puppeteer 兼容。浏览器默认下载到 $HOME/.cache/puppeteer 文件夹（从 Puppeteer v19.0.0 开始）。请参阅 配置 以了解配置选项和环境变量以控制下载行为。
如果您将使用 Puppeteer 的项目部署到托管提供商（如 Render 或 Heroku），您可能需要重新配置缓存的位置以位于项目文件夹内（请参阅下面的示例），因为并非所有托管提供商都将 $HOME/.cache 包含在项目的部署中。
对于没有浏览器安装的 Puppeteer 版本，请参阅 puppeteer-core。
如果与 TypeScript 一起使用，则支持的最低 TypeScript 版本为 4.7.4。
配置
Puppeteer 使用多个默认值，可以通过配置文件进行自定义。
例如，要更改 Puppeteer 用于安装浏览器的默认缓存目录，您可以在应用程序的根目录中添加一个 .puppeteerrc.cjs（或 puppeteer.config.cjs），其内容为
const {join} = require('path');
/**
* @type {import("puppeteer").Configuration}
*/
module.exports = {
// Changes the cache location for Puppeteer.
cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};
添加配置文件后，您需要移除并重新安装puppeteer才能使配置生效。
有关更多信息，请参阅配置指南。
puppeteer-core
从 v1.7.0 版本开始，我们发布了两个包
puppeteer 是一个用于浏览器自动化的产品。安装后，它会下载一个 Chrome 版本，然后使用puppeteer-core驱动它。作为最终用户产品，puppeteer 使用合理的默认值自动化了多个工作流程可以自定义。
puppeteer-core 是一个库，用于帮助驱动任何支持 DevTools 协议的内容。作为库，puppeteer-core 完全通过其编程接口驱动，这意味着不假设任何默认值，并且puppeteer-core 安装后不会下载 Chrome。
如果您要连接到远程浏览器或自己管理浏览器，则应使用puppeteer-core。如果您自己管理浏览器，则需要使用显式puppeteer.launch调用executablePath（或channel，如果它安装在标准位置）。
使用puppeteer-core时，请记住更改导入
import puppeteer from 'puppeteer-core';
用法
Puppeteer 遵循 Node 的最新维护 LTS 版本。
Puppeteer 对使用其他浏览器测试框架的人来说很熟悉。您可以启动/连接一个浏览器，创建一些页面，然后使用Puppeteer 的 API操作它们。
示例
以下示例搜索 developer.chrome.com 中包含文本“automate beyond recorder”的博客文章，点击第一个结果并打印博客文章的完整标题。
import puppeteer from 'puppeteer';
(async () => {
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Navigate the page to a URL
await page.goto('https://developer.chrome.com/');
// Set screen size
await page.setViewport({width: 1080, height: 1024});
// Type into search box
await page.type('.devsite-search-field', 'automate beyond recorder');
// Wait and click on first result
const searchResultSelector = '.devsite-result-item-link';
await page.waitForSelector(searchResultSelector);
await page.click(searchResultSelector);
// Locate the full title with a unique string
const textSelector = await page.waitForSelector(
'text/Customize and automate'
);
const fullTitle = await textSelector?.evaluate(el => el.textContent);
// Print the full title
console.log('The title of this blog post is "%s".', fullTitle);
await browser.close();
})();
默认运行时设置
1. 使用无头模式
默认情况下，Puppeteer 在 无头模式 下启动 Chrome。
const browser = await puppeteer.launch();
// Equivalent to
const browser = await puppeteer.launch({headless: true});
在 v22 之前，Puppeteer 默认启动 旧的无头模式。旧的无头模式现在被称为 chrome-headless-shell，并作为独立的二进制文件提供。chrome-headless-shell 的行为与常规 Chrome 不完全匹配，但目前对于不需要完整 Chrome 功能集的自动化任务来说，它更有效率。如果性能对您的用例更重要，请按照以下步骤切换到 chrome-headless-shell
const browser = await puppeteer.launch({headless: 'shell'});
要启动 Chrome 的“有头”版本，请在启动浏览器时将 headless 设置为 false 选项
const browser = await puppeteer.launch({headless: false});
2. 运行捆绑的 Chrome 版本
默认情况下，Puppeteer 会下载并使用特定版本的 Chrome，因此其 API 保证开箱即用。要将 Puppeteer 与其他版本的 Chrome 或 Chromium 一起使用，请在创建 Browser 实例时传入可执行文件的路径
const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'});
您也可以将 Puppeteer 与 Firefox 一起使用。有关更多信息，请参阅 跨浏览器支持状态。
有关 Chromium 和 Chrome 之间差异的说明，请参阅 这篇文章。 这篇文章 描述了 Linux 用户的一些差异。
3. 创建新的用户配置文件
Puppeteer 创建自己的浏览器用户配置文件，它会在每次运行时清理。
使用 Docker
查看我们的 Docker 指南。
使用 Chrome 扩展程序
查看我们的 Chrome 扩展程序指南。
资源
贡献
查看我们的 贡献指南，以了解 Puppeteer 开发的概述。