puppeteer

用 JavaScript 轻松操控无头浏览器，搞定自动化测试与网页抓取。

Puppeteer 是一个由 Google 维护的 Node.js 库，提供高级 JavaScript API 来控制无头 Chrome 或 Firefox 浏览器。它解决了开发者需要以编程方式操作浏览器的痛点，无需手动打开界面即可完成自动化任务。其核心能力包括：页面 DOM 操作、表单提交、键盘输入、网络请求拦截与模拟、生成页面截图和 PDF、爬取单页应用（SPA）内容、模拟移动设备等。Puppeteer 通过 DevTools 协议与浏览器通信，支持有头/无头模式切换，广泛用于端到端测试、网页抓取、性能监控和自动化运维。它内置了浏览器下载管理，简化环境配置，并提供丰富的 API 文档和示例。

开源 free 自动化工作流

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 95622

维护状态活跃

是否开源是

定价模式 free

项目数据

分类自动化工作流

开发团队puppeteer

所属国家

官网地址https://pptr.dev

GitHubhttps://github.com/puppeteer/puppeteer

定价模式free

价格说明开源项目，完全免费，无付费版本。

访问状态

是否开源是

开源协议Apache-2.0

主要语言TypeScript

技术栈/模型automation,chrome,chromium,developer-tools,firefox,headless-chrome,node-module,testing,web

GitHub 星标★ 95622

30天Star增速

HF 下载量

上线时间2017-05-09 00:00:00

最近更新2026-09-26 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-10

浏览次数17

使用教程

难度：入门约 10 分钟部署方式：库/依赖 5 步

环境要求

Node.js 运行环境（Puppeteer 是 Node.js 库/Node 模块）
支持 npm、pnpm、Yarn、Bun 或 Deno 等包管理器
使用 puppeteer-core 时需自备 Chrome 或 Firefox 浏览器
所在系统能够运行 Chrome 或 Firefox 浏览器

安装与启动步骤

1安装 Puppeteer

在 Node.js 项目中执行该命令，安装过程中会自动下载与之兼容的 Chrome 浏览器。
```
npm i puppeteer
```
2安装核心库

改用 puppeteer-core 只安装库本身、不下载 Chrome，适合已有浏览器或自行指定浏览器可执行文件。
```
npm i puppeteer-core
```
3手动装浏览器

现代包管理器默认阻止依赖安装脚本，此时安装不会下载浏览器，需手动执行此命令补装所需浏览器。
```
npx puppeteer browsers install
```
4放行安装脚本

另一种做法是配置包管理器允许安装脚本运行，例如在 package.json 中把 "puppeteer" 加入 "allowScripts"。
5可选装 MCP

README 提到可安装基于 Puppeteer 的 chrome-devtools-mcp 用于浏览器自动化与调试，安装方式见其仓库说明。

关键配置

配置项	必填	说明	示例
`allowScripts`	否	package.json 中用于放行 puppeteer 安装脚本、使其自动下载浏览器	`{"allowScripts": ["puppeteer"]}`

如何确认成功

安装命令无报错，且在安装脚本未被阻止时浏览器已随之下载完成，即可在代码中引入 puppeteer 使用。

常见问题

Q：安装后运行时报找不到浏览器怎么办？

A：多半是包管理器默认阻止了依赖安装脚本，导致安装时未下载浏览器。执行 npx puppeteer browsers install 手动下载，或把 puppeteer 加入 allowScripts 放行安装脚本。

Q：puppeteer 和 puppeteer-core 有什么区别？

A：npm i puppeteer 会在安装时下载兼容版本的 Chrome；puppeteer-core 只安装库、不下载浏览器，需要你自行提供并指定浏览器。

Q：Puppeteer 能控制 Firefox 吗？

A：可以。它通过 DevTools Protocol 或 WebDriver BiDi 控制 Chrome 或 Firefox，具体支持情况见官方文档。

Q：默认是打开浏览器界面还是无头运行？

A：默认以无头模式运行，也就是没有可见界面，适合服务器端自动化。

注意事项

本项目是库/依赖，不是独立服务，安装后无需启动端口。
官方文档、API、FAQ 与故障排查入口见 https://pptr.dev。
现代包管理器默认阻止依赖安装脚本，请确认浏览器是否真的下载成功。
Puppeteer 默认无头运行，可通过 API 切换为有头模式。

核心亮点

API 设计直观，上手快，几行代码即可实现截图或生成 PDF
与 Chrome DevTools 协议深度集成，支持网络拦截、性能追踪等高级功能
自动管理浏览器下载，无需手动安装，环境配置简单

不足之处

默认只支持 Chromium 系，对 Firefox 支持仍在完善中
浏览器实例资源占用较高，并发场景下性能开销大

适用场景

端到端测试：模拟用户操作验证 Web 应用功能
网页爬虫：抓取 SPA 动态渲染内容
自动化报表：定时截取网页图表或生成 PDF 报告

替代项目

Playwright、Selenium、Cypress

项目介绍

puppeteer 是自动化工作流领域的开源项目，由 puppeteer 开发，2017 年首次发布。

在全站 13,148 个收录项目中，它的 GitHub 星标数（95,622）位列前 1%，在自动化工作流分类的 520 个项目里位列前 1%。

近 45 天，它的 GitHub 星标从 95,455 增加到 95,622，净增 167。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-26。完全免费，无付费版本。

它主要面向的使用场景是：端到端测试：模拟用户操作验证Web应用功能。同类可对比的替代方案包括 Playwright、Selenium、Cypress。

上一篇：data-engineering

下一篇：n8n