Puppeteer：用JavaScript控制Chrome和Firefox的无头浏览器自动化库 | puppeteer

📌 项目地址：puppeteer/puppeteer | ⭐ 94,604 颗星 | 🔧 TypeScript | 📜 未标注

核心价值：用代码操作浏览器

Puppeteer是一个JavaScript库，通过DevTools协议或WebDriver BiDi提供了高级API来驱动Chrome或Firefox。默认在无头模式下运行（没有可见的UI），适合做自动化测试、网页截图、爬虫、表单填充、性能监控等任务。它由Chrome团队维护，是Node.js生态中最流行的浏览器控制工具之一。

快速上手：安装到第一个脚本

安装可以选择完整版（自动下载兼容的Chrome）或轻量版（仅安装库，需自己处理浏览器）。

npm i puppeteer          # 安装时自动下载Chrome
npm i puppeteer-core     # 仅安装库，不下载浏览器

注意：现代包管理器（npm、pnpm、Yarn、Bun、Deno）默认阻止安装脚本，导致浏览器不会自动下载。如果安装后运行报错，需要手动下载浏览器：

npx puppeteer browsers install

或者在package.json中对npm设置允许脚本：

"allowScripts": ["puppeteer"]

下面是一个完整的示例（来自README），演示打开页面、搜索并获取结果标题：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

await page.goto('https://developer.chrome.com/');
await page.setViewport({width: 1080, height: 1024});

// 键盘操作：按 '/' 打开搜索菜单
await page.keyboard.press('/');

// 用ARIA标签名定位输入框并输入文字
await page.locator('::-p-aria(Search)').fill('automate beyond recorder');

// 点击第一个搜索结果
await page.locator('.devsite-result-item-link').click();

// 用文本选择器找到包含特定文字的标题
const textSelector = await page
  .locator('::-p-text(Customize and automate)')
  .waitHandle();
const fullTitle = await textSelector?.evaluate(el => el.textContent);

console.log('The title of this blog post is "%s".', fullTitle);
await browser.close();

核心功能：灵活的页面控制与定位

Puppeteer的API覆盖了浏览器操作的几乎全部场景：

• 页面导航：page.goto(url)、前进、后退、等待页面加载。
• 视图控制：page.setViewport({width, height}) 调整窗口大小。
• 键盘与鼠标：page.keyboard.press()、page.mouse.click()等模拟用户输入。
• 元素定位：提供“定位器”（Locator）机制，支持多种选择器：
• ::-p-aria(Search) 基于无障碍名称查找输入框。
• ::-p-text(文字内容) 根据可见文本匹配元素。
• ::-p-xpath(//div) 使用XPath。
• 还可以组合 .css-selector 和 waitHandle() 等待元素出现并获取其句柄。
• 脚本执行：通过element.evaluate()在浏览器上下文中运行任意JavaScript，获取或修改页面数据。
• 截图与PDF：page.screenshot()、page.pdf()。
• 网络拦截：监听请求、修改响应、模拟离线状态。

这些功能让开发者能精确地模拟用户行为，并读取页面信息。

与同类工具的区别

与Selenium、Playwright相比，Puppeteer的特点是：

• 原生支持Chrome/Firefox：由Chrome团队维护，对Chromium的支持最及时。通过WebDriver BiDi也可以控制Firefox（实验性）。
• 默认无头：安装后即可运行，无需额外驱动或配置。
• API更简洁现代：基于Promise，与async/await自然融合，减少了回调嵌套。
• 定位器系统：Puppeteer的locator方法比传统的page.$(selector)更智能，可以自动等待元素就绪、支持模糊匹配和容错。
• MCP协议支持：新特性chrome-devtools-mcp可作为MCP服务器使用，支持AI助手直接调用浏览器进行自动化调试。

不过Playwright支持多浏览器（Chrome、Firefox、WebKit）且更强调跨浏览器一致性；Selenium支持更多语言。选择时按需考虑。

注意事项

1. 浏览器下载问题：如安装时未自动下载，运行前需执行npx puppeteer browsers install。如果服务器环境无法下载，可以使用puppeteer-core自行指定浏览器路径。
2. 许可证：Apache-2.0，商用友好。
3. 局限性：Puppeteer主要面向Chrome/Firefox，不支持Safari（WebKit）。如果项目需要完整跨浏览器覆盖，可以配合Playwright或Selenium。
4. 运行环境：需要Node.js 18+。在无图形界面的服务器（如Linux）上，可能需要安装系统依赖（如libnss3等），官方提供了故障排查页面：https://pptr.dev/troubleshooting

更多细节可查阅官方文档：入门指南(https://pptr.dev/docs)、API参考(https://pptr.dev/api)、FAQ(https://pptr.dev/faq)。