Puppeteer

Puppeteer 是什么

Puppeteer 是由 Google 维护的 JavaScript/TypeScript 库，提供一套高层 API 来操控 Chrome 与 Firefox。它底层通过 DevTools Protocol 或 WebDriver BiDi 与浏览器通信，默认以无头（无可见界面）模式运行。

项目以 Apache-2.0 协议开源，主语言为 TypeScript，官方站点为 pptr.dev。

核心能力

• 页面导航与交互：打开页面、设置视口、模拟键盘鼠标输入、点击与填写表单。
• 元素定位：支持 CSS 选择器，以及 ::-p-aria()、::-p-text() 等基于可访问性与文本的定位方式。
• 内容提取：在页面上下文中执行脚本，读取 DOM 文本、属性与计算结果。
• 截图与 PDF：将页面渲染结果导出为图片或 PDF，常用于报表与预览服务。
• 多浏览器支持：同一套 API 覆盖 Chrome 与 Firefox。

安装与浏览器下载

npm i puppeteer        # 安装时下载兼容版本的 Chrome
npm i puppeteer-core   # 仅作为库安装，不下载浏览器

需要注意：npm、pnpm、Yarn、Bun、Deno 等现代包管理器默认会拦截依赖的安装脚本。若安装脚本被阻止，Puppeteer 不会在安装阶段下载浏览器，运行时可能报错。此时可手动执行：

npx puppeteer browsers install

或在 package.json 中允许该脚本运行。

快速示例

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('/');
await page.locator('::-p-aria(Search)').fill('automate beyond recorder');
await page.locator('.devsite-result-item-link').click();

const handle = await page.locator('::-p-text(Customize and automate)').waitHandle();
const title = await handle?.evaluate(el => el.textContent);
console.log(title);

await browser.close();

与 AI 工作流的结合

Puppeteer 生态中提供了 chrome-devtools-mcp，这是一个基于 Puppeteer 的 MCP 服务端，可用于浏览器自动化与调试；同时项目也在实验性支持 WebMCP API，方便把浏览器操作能力接入 Agent 类应用。

适用与注意事项

Puppeteer 适合端到端测试、截图/PDF 生成、网页采集与性能分析等场景。在生产环境使用时，建议关注以下几点：

• 无头环境需准备必要的系统依赖，并合理配置沙箱参数。
• 高并发抓取时注意内存与进程管理，必要时复用浏览器实例。
• 升级 Puppeteer 时留意其绑定的浏览器版本是否匹配。