Puppeteer

Chrome 浏览器自动化 Node.js 库

测试工具浏览器自动化Chromium截图工具

Puppeteer 是 Google Chrome 团队维护的 Node.js 库，通过 DevTools Protocol 控制 Chrome/Chromium，用于网页截图、PDF 生成、爬虫和浏览器自动化，既是底层自动化工具也可用于 E2E 测试。

访问官网

Puppeteer Chrome 浏览器自动化技术调研

Puppeteer 是 Google Chrome 团队维护的 Node.js 库，通过 DevTools Protocol 控制 Chrome/Chromium（及实验性 Firefox），用于网页截图、PDF 生成、爬虫、性能分析和浏览器自动化。它既是底层自动化工具，也可用于 E2E 测试，但通常推荐配合 @playwright/test 或 jest-puppeteer 构建完整测试套件。

一、基本信息

维度	关键指标 / 描述
技术标签	浏览器自动化 / Chromium / 截图 / PDF / 爬虫
开发商	Google Chrome 团队
官方网站	https://pptr.dev/
GitHub 仓库	puppeteer/puppeteer
npm 包	`puppeteer` / `puppeteer-core`
许可协议	Apache 2.0
首次发布	2017 年
当前版本	Puppeteer 24.x（2026 年）
生态成熟度	极高（自动化领域标准库之一）

二、技术定位与简介

Puppeteer 提供高级 API 控制无头或有头 Chrome：

页面导航：page.goto、click、type。
截图与 PDF：page.screenshot、page.pdf。
DOM 操作：page.$、page.evaluate。
网络拦截：page.setRequestInterception。
性能追踪：page.tracing、Chrome DevTools 集成。
无头新特性：headless: 'new' 模式。

与 Playwright 相比，Puppeteer 更底层、更聚焦 Chromium；Playwright 是多浏览器测试框架，API 更面向测试场景。

三、快速上手安装说明

1. 安装

pnpm add puppeteer
# 或仅连接已有 Chrome
pnpm add puppeteer-core

2. 基础脚本

import puppeteer from 'puppeteer'
 
const browser = await puppeteer.launch({ headless: true })
const page = await browser.newPage()
await page.goto('https://example.com')
await page.screenshot({ path: 'example.png', fullPage: true })
await browser.close()

3. 生成 PDF

await page.pdf({
  path: 'page.pdf',
  format: 'A4',
  printBackground: true,
})

4. 等待与选择器

await page.waitForSelector('#content')
await page.click('button.submit')
await page.type('#email', '[email protected]')

5. 页面内执行 JS

const title = await page.evaluate(() => document.title)

四、核心特性

1. 自动下载 Chromium

puppeteer 包捆绑兼容版本浏览器。

2. puppeteer-core

连接系统已安装 Chrome，减小部署体积。

3. 无头与有头模式

调试时 headless: false 可视化。

4. 设备模拟

page.emulate(puppeteer.devices['iPhone 14'])

5. 网络控制

拦截、修改、阻断请求。

6. Coverage API

JS/CSS 覆盖率采集。

7. Chrome DevTools Protocol

底层完整协议访问能力。

五、适用场景

1. 黄金适用场景

服务端截图、缩略图、OG 图生成。
HTML 转 PDF 报告。
爬虫与数据抓取（遵守 robots 与法律）。
性能基准与 Lighthouse 集成。
简单自动化脚本。
Next.js 等框架的 @sparticuz/chromium 无服务器场景。

2. 局限适用场景

完整 E2E 测试套件（优先 Playwright/Cypress）。
跨 Firefox/Safari 测试。
需要内置断言、重试、报告器。

六、技术亮点

1. 官方 Chromium 绑定

与 Chrome 版本同步，协议支持最新。

2. API 简洁

学习曲线低于原始 CDP。

3. 无服务器友好

puppeteer-core + @sparticuz/chromium 用于 AWS Lambda 等。

4. 生态庞大

大量教程、中间件、封装库。

5. 与 Chrome DevTools 一致

调试心智与 DevTools 相通。

七、核心概念与架构

digraph Puppeteer_Architecture {
  rankdir=LR
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Node [label="Node.js Script", fillcolor="#bae6fd"]
  Puppeteer [label="Puppeteer API"]
  CDP [label="Chrome DevTools Protocol"]
  Chrome [label="Chromium"]
  Page [label="Page / Frame"]
 
  Node -> Puppeteer
  Puppeteer -> CDP
  CDP -> Chrome
  Chrome -> Page
}

八、技术局限与边界

主要 Chromium：跨浏览器能力弱于 Playwright。
非测试框架：无内置 expect、并行 runner。
资源占用：Chromium 内存较大。
反爬对抗：需额外策略，非 Puppeteer 专长。
自动等待：需手动 waitForSelector，易 flaky。
Serverless 限制：冷启动与包体积需优化。

九、生态地图

类别	工具
测试	jest-puppeteer、pptr-testing
E2E 替代	Playwright、Cypress
无服务器	@sparticuz/chromium
爬虫	puppeteer-extra、stealth 插件
框架	Next.js OG、Remotion

十、生态集成

方向	说明
Jest	jest-puppeteer 预设。
Lighthouse	性能审计流水线。
Playwright	同源团队，测试选 Playwright。
Vercel/OG	动态 OG 图片生成。

十一、开发与工程化

1. Docker 部署

使用官方 Puppeteer Docker 镜像或安装 Chromium 依赖。

2. 无服务器 PDF/截图

import chromium from '@sparticuz/chromium'
import puppeteer from 'puppeteer-core'
 
const browser = await puppeteer.launch({
  args: chromium.args,
  executablePath: await chromium.executablePath(),
  headless: chromium.headless,
})

3. 测试分工

自动化脚本用 Puppeteer；E2E 用 Playwright。

十二、性能与安全

复用 browser 实例，多页面共享。
browser.close() 防止进程泄漏。
爬虫遵守网站 ToS 与 robots.txt。
勿在 evaluate 中处理不可信脚本。
Serverless 注意执行超时与内存上限。

十三、技术对比

工具	优势	局限	适合
Puppeteer	Chromium 官方、底层灵活	非测试框架	截图/PDF/脚本
Playwright	测试完备、三引擎	较重	E2E 测试
Selenium	最广浏览器	慢、老旧	遗留企业

十四、最佳实践

E2E 优先 Playwright，Puppeteer 做自动化任务。
生产用 puppeteer-core + 系统 Chrome 减小体积。
显式 waitForSelector 或 Playwright 风格等待封装。
批量任务复用 browser，分页 parallel 控制并发。
Serverless 使用 @sparticuz/chromium 优化包大小。
截图前 page.setViewport 固定尺寸。
错误时保存 screenshot 辅助排障。

十五、学习与社区资源

官方文档：https://pptr.dev/
GitHub：https://github.com/puppeteer/puppeteer
Chrome DevTools Protocol：https://chromedevtools.github.io/devtools-protocol/