Puppeteer：Chrome 和 Firefox 的 JavaScript API

这是什么

Puppeteer 是一个由 Google 主导开发的高阶 JavaScript/TypeScript 库，旨在通过 DevTools Protocol 或 WebDriver BiDi 协议控制 Chrome 或 Firefox 浏览器。它允许开发者以编程方式自动化浏览器操作，默认情况下以无头模式（Headless，即无可见 UI 界面）运行，非常适合服务器端环境。

该项目是 GitHub 上极受欢迎的开源项目之一（Stars 超过 94,000），其核心定位是提供一套稳定、高效的 API 来模拟真实用户与网页的交互，包括页面导航、DOM 操作、截图、PDF 生成以及性能监控等。

解决的问题

在现代 Web 开发和运维中，Puppeteer 主要解决了以下痛点：

1. 浏览器自动化缺失：传统 Web 测试或爬虫往往依赖底层 HTTP 请求，无法执行 JavaScript 渲染的页面，也无法模拟用户交互（如点击、输入）。Puppeteer 提供了完整的浏览器实例控制能力。
2. 跨环境一致性：通过锁定特定版本的 Chromium 浏览器，Puppeteer 确保了自动化脚本在不同机器（开发机、CI/CD 服务器、生产环境）上运行行为的一致性，避免了因浏览器版本差异导致的“在我机器上是好的”这类问题。
3. 无头模式下的调试困难：虽然默认无头运行节省资源，但 Puppeteer 提供了丰富的调试工具链，使得在无 UI 环境下进行页面状态捕获、截图和日志记录变得容易。
4. 现代 Web 应用测试瓶颈：随着单页应用（SPA）和复杂前端框架的普及，传统的 DOM 测试难以覆盖真实用户场景。Puppeteer 能够等待网络请求完成、元素可见等真实用户感知的事件，提供更接近真实的测试体验。

核心功能

• 生成页面截图和 PDF：能够精确截取网页的完整内容或指定区域，生成高质量的 PNG/JPEG 截图或 PDF 文件，常用于生成报告或归档页面状态。
• 爬取 SPA（单页应用）并生成预渲染内容（即“SSR”静态化）：对于由 JavaScript 动态渲染内容的页面，Puppeteer 可以等待脚本执行完毕后再抓取最终 DOM，解决传统爬虫无法获取动态数据的问题。
• 自动化表单提交、UI 测试、键盘输入：模拟真实用户操作，包括点击按钮、填写表单、上传文件、模拟键盘快捷键等，适用于端到端（E2E）测试。
• 捕获网站的 timeline trace：记录浏览器执行过程中的性能数据，帮助开发者分析页面加载性能、识别瓶颈。
• 调试现代 Web 应用：开发者可以附加调试器，逐步执行代码，检查 DOM 状态、网络请求和 Console 日志，极大简化了前端调试流程。
• 支持 WebDriver BiDi：除了传统的 DevTools Protocol，Puppeteer 也支持实验性的 WebDriver BiDi 协议，为未来向 W3C 标准靠拢提供了兼容性支持。

亮点 / 与同类相比

• 与 Selenium 相比：

  • API 更现代：Puppeteer 基于 Promise，代码更简洁、异步处理更自然；Selenium 传统上基于回调或同步阻塞，虽然新版也支持异步，但 Puppeteer 的设计更贴合现代 JS 开发习惯。
  • 集成度更高：Puppeteer 默认捆绑兼容版本的 Chromium，开箱即用，无需额外配置浏览器驱动；Selenium 需要手动管理浏览器驱动（WebDriver）和浏览器版本匹配。
  • 性能与稳定性：在 Chrome/Chromium 生态中，Puppeteer 对 DevTools Protocol 的直接访问使其在某些操作（如拦截网络请求、修改 Headers）上比 Selenium 更灵活、更高效。

• 与 Playwright 相比：

  • 生态成熟度：Puppeteer 历史更悠久，社区资源、教程和第三方库更为丰富。
  • 浏览器支持：Puppeteer 主要专注于 Chromium 内核浏览器（Chrome, Edge, Opera 等），对 Firefox 的支持是实验性的；而 Playwright 由 Microsoft 开发，原生支持 Chromium、Firefox 和 WebKit，跨浏览器测试能力更强。
  • 协议差异：Puppeteer 主要依赖 DevTools Protocol（虽新增 BiDi 支持），Playwright 则基于 CDP 和自身构建的协议，对多浏览器支持更统一。

• 安装与依赖管理：

  • 提供 puppeteer（自动下载兼容浏览器）和 puppeteer-core（仅库文件，需手动指定浏览器路径）两种安装方式，适应不同部署场景。
  • 注意：现代包管理器（npm, pnpm, Yarn, Bun, Deno）默认阻止安装脚本，可能导致浏览器未下载。需手动运行 npx puppeteer browsers install 或配置 allowScripts。

适合谁用 / 上手

适合人群：

• 前端开发者：用于编写端到端（E2E）测试，验证复杂交互和渲染逻辑。
• 后端/全栈开发者：用于生成 PDF 报告、截图缩略图、爬取动态网页内容。
• QA 测试工程师：自动化回归测试，模拟用户操作流程。
• DevOps/SRE：在 CI/CD 管道中集成浏览器自动化任务，监控页面可用性。

上手指南：

1. 安装：

   npm i puppeteer
   

   注意：如果包管理器阻止脚本，请手动安装浏览器：

   npx puppeteer browsers install
   

2. 基本示例：

   import puppeteer from 'puppeteer';
   
   async function run() {
     // 启动浏览器
     const browser = await puppeteer.launch();
     const page = await browser.newPage();
     
     // 导航到目标 URL
     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();
   }
   
   run().catch(console.error);
   

3. 进阶技巧：

   • 使用 puppeteer-core 在已有浏览器环境中运行，避免重复下载。
   • 结合 chrome-devtools-mcp 实现基于 MCP 协议的浏览器自动化和调试。
   • 利用 page.on('request') 和 page.on('response') 拦截和修改网络请求，实现更复杂的爬取或测试逻辑。