Puppeteer：Google 官方 Node.js 无头浏览器库｜部署与使用全指南
Puppeteer 是 Google Chrome 团队维护的 Node.js 库，通过 Chrome DevTools Protocol 或 WebDriver BiDi 高层控制 Chrome / Firefox，默认无头运行。本文按官方 README 给出 npm 安装、浏览器下载、最小示例与常见问题。
1. 项目简介与定位
Puppeteer 是一个 JavaScript 库，提供高层 API，通过 Chrome DevTools Protocol 或 WebDriver BiDi 控制 Chrome 或 Firefox。它默认以无头（headless，无可视化 UI）方式运行浏览器，也可配置为完整模式。Puppeteer 由 Google Chrome 团队官方维护，是 Node 生态里最常用的浏览器自动化库之一。
1.1 核心信息一览
| 项 | 内容 |
|---|---|
| 项目名 | Puppeteer |
| 仓库 | https://github.com/puppeteer/puppeteer |
| 官网 / 文档 | https://pptr.dev |
| 主语言 | TypeScript / JavaScript |
| 运行时 | Node.js（含 Deno、Bun 兼容） |
| 控制协议 | Chrome DevTools Protocol / WebDriver BiDi |
| 支持浏览器 | Chrome（自带下载）、Firefox（puppeteer 实验支持） |
| 许可证 | Apache License 2.0 |
| 部署形态 | npm 包，本地库 |
1.2 适用场景
- 单页应用（SPA）的端到端测试
- 生成页面 PDF 与截图
- 爬取需要 JavaScript 渲染的页面内容
- 自动化提交表单、UI 调试、性能分析（配合 Trace）
- 作为 MCP server 后端驱动浏览器（见
chrome-devtools-mcp）
1.3 能力边界（官方口径）
Puppeteer 是库，不是测试框架：它负责启动浏览器与操作页面，不提供断言、报告、用例编排。需要 Jest / Mocha / Vitest 等测试框架配合。它原生只跑在 Node 上，Python / Go 生态请选择 Selenium 或 chromedp。
2. 开源协议
Puppeteer 采用 Apache License 2.0。
3. 官方仓库链接
- 仓库：https://github.com/puppeteer/puppeteer
- 文档站（Get started / API / FAQ / Troubleshooting）：https://pptr.dev
- API 参考：https://pptr.dev/api
- 常见问题：https://pptr.dev/faq
- 排错指南：https://pptr.dev/troubleshooting
- WebDriver BiDi 指南：https://pptr.dev/webdriver-bidi
- MCP server（基于 Puppeteer）：https://github.com/ChromeDevTools/chrome-devtools-mcp
4. 前置要求
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | 18+（LTS 推荐） | node -v 查看 |
| npm / pnpm / yarn / bun | 任一现代包管理器 | 见下方安装注意事项 |
| 操作系统 | Linux / macOS / Windows | 服务器场景建议 Linux + headless |
| 系统依赖（Linux） | Chrome 运行时依赖库 | 用官方 puppeteer 包会自动下载兼容 Chrome；若用
puppeteer-core 需自行装 Chrome |
| 磁盘 | 约 300 MB | 自带 Chromium 下载体积 |
官方 README 提示：现代包管理器（含 npm、pnpm、Yarn、Bun、Deno）默认阻止依赖安装脚本执行。若 install script 被阻止，Puppeteer 在安装时不会下载浏览器，运行时会报错。
5. 安装部署
5.1 标准安装（自动下载兼容 Chrome）
npm i puppeteer
# 安装过程中会自动下载一份与当前 Puppeteer 版本兼容的 Chrome5.2 作为库使用（不下载 Chrome，复用本机 Chrome）
npm i puppeteer-corepuppeteer-core 不下载浏览器，适合你已经在系统里装了
Chrome / Edge，或在 Docker 镜像里已经内置 Chromium 的场景。
5.3 install script 被包管理器拦截时手动下载浏览器
npx puppeteer browsers install也可以在 package.json 中把 puppeteer 加入
allowScripts（npm RFC 868 之后），允许其 install script
运行。
5.4 使用 Docker 官方镜像
Google 官方提供 puppeteer/puppeteer Docker 镜像，内置
Node 与 Chromium 及其所有系统依赖：
docker pull puppeteer/puppeteer
docker run -i --rm --init --cap-add=SYS_ADMIN \
-v "$(pwd)":/app -w /app \
puppeteer/puppeteer node your-script.js6. 最小示例代码
下面是官方 README 给出的 TypeScript
示例：启动浏览器、打开新标签、访问 Chrome 开发者文档、按 /
打开搜索框、输入关键词、点击第一条结果、打印文章标题。
import puppeteer from 'puppeteer';
// 或：import puppeteer from 'puppeteer-core';
// 启动浏览器并打开一个空白页
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('/');
// 通过无障碍名称向搜索框输入
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();6.1 headless 与常用启动参数
const browser = await puppeteer.launch({
headless: true, // 默认 true；false 可看到浏览器窗口
defaultViewport: { width: 1280, height: 800 },
args: ['--no-sandbox', '--disable-dev-shm-usage'], // 容器内必须
});6.2 截图与 PDF
await page.goto('https://example.com');
await page.screenshot({ path: 'example.png', fullPage: true });
await page.pdf({ path: 'example.pdf', format: 'A4' });7. 配置项
| 配置 | 作用 | 默认值 |
|---|---|---|
headless |
是否无头运行 | true（新版 'shell' 亦可） |
defaultViewport |
默认页面视口 | 800×600 |
executablePath |
指定浏览器可执行文件路径 | 自动下载的 Chrome |
args |
透传给 Chrome 的命令行参数 | [] |
--no-sandbox |
容器内关闭沙箱 | 不默认开 |
--disable-dev-shm-usage |
共享内存走 /tmp，避免 /dev/shm 过小 | 不默认开 |
PUPPETEER_CACHE_DIR |
浏览器下载缓存目录 | ~/.cache/puppeteer |
PUPPETEER_SKIP_DOWNLOAD |
跳过 postinstall 浏览器下载 | 不设置 |
protocol |
cdp 或 webDriverBiDi |
视版本而定 |
8. 常见问题
Q1：Could not find Chrome (ver. xxx)
启动失败？ A：install script 被包管理器拦截。运行
npx puppeteer browsers install 手动下载，或改用
puppeteer-core + 本机 Chrome。
Q2：Docker 里启动 Chrome 立刻崩溃？ A：容器内必须加
--no-sandbox --disable-dev-shm-usage，并使用官方
puppeteer/puppeteer 镜像（已装好全部系统依赖）。
Q3：puppeteer 和 puppeteer-core
有什么区别？ A：puppeteer 会下载一份兼容
Chrome；puppeteer-core
不下载，连接你自己指定的浏览器。生产环境推荐 puppeteer-core
+ 官方镜像。
Q4：如何拦截网络请求 / 修改响应？ A：使用
page.setRequestInterception(true) +
page.on('request', ...)；或在新版里用
page.createCDPSession() 直接调 CDP。
Q5：为什么我 npm install 很慢？
A：Puppeteer postinstall 会从 Google Storage 下载
Chromium。国内环境可设置 PUPPETEER_DOWNLOAD_BASE_URL
指向镜像，或先 PUPPETEER_SKIP_DOWNLOAD=1 npm i
再手动装。
9. 与同类工具对比
| 维度 | Puppeteer | Playwright | Selenium | chromedp |
|---|---|---|---|---|
| 出品方 | Google Chrome 团队 | Microsoft | 社区 / W3C | 社区 |
| 语言 | 仅 Node.js | Node / Python / Java / .NET | Python / Java / JS / C# / Ruby | 仅 Go |
| 协议 | CDP / WebDriver BiDi | CDP + 自家 | W3C WebDriver | CDP |
| 浏览器 | 主力 Chrome，实验支持 Firefox | 全平台全浏览器 | 全浏览器 | Chrome / Chromium |
| 自带测试 runner | 否 | 是 | 否 | 否 |
| 学习曲线 | 低，API 直观 | 低 | 中 | 中 |
Puppeteer 与 Playwright 高度重叠：只跑 Chrome、脚本短小、做截图/PDF/抓取时选 Puppeteer；需要多浏览器、并行 trace、test runner 选 Playwright。
10. 许可
Apache License 2.0。详见 https://github.com/puppeteer/puppeteer/blob/main/LICENSE 。
11. 责任使用声明
使用 Puppeteer 自动化访问任何站点时，请遵守目标站点的
robots.txt
与服务条款（ToS）。请合理控制并发与启动频率，在请求之间加入延时，避免对目标服务器造成压力。请勿用
Puppeteer
绕过登录验证、付费墙、验证码或反爬系统。请勿批量抓取、存储或传播个人隐私数据。本工具仅应用于公开数据的合法研究、自身站点的
E2E
测试与授权范围内的自动化任务。请尊重网页内容的版权，二次发布抓取结果需获得权利人许可。