Puppeteer 快速上手：安装、浏览器管理与首次自动化实践（源码级解析）

Puppeteer 是一个为 Chrome 和 Firefox 提供高层 JavaScript API 的库，默认以无头（headless，无可见界面）模式运行，通过 DevTools Protocol 或 WebDriver BiDi 两种协议驱动浏览器。本篇基于仓库根目录的 README.md 展开，并结合 packages/puppeteer 与 packages/browsers 的源码，完整讲解两种安装方式的差异、浏览器下载机制的底层实现、安装脚本被包管理器阻断时的补救手段，以及一个可直接运行的自动化示例。读完后，你将能正确完成 Puppeteer 的安装配置，并理解“安装时自动下载浏览器”背后的完整调用链。

Puppeteer 是什么

根据 README.md 的定义，Puppeteer 是一个 JavaScript 库，提供控制 Chrome 或 Firefox 的高层 API，底层通信协议有两种可选路径：

• DevTools Protocol（CDP）：Chrome DevTools 使用的远程调试协议；
• WebDriver BiDi：新一代的 Web 自动化双向协议，仓库中的 docs/webdriver-bidi.md 和根目录 package.json 中的 test:chrome:bidi、test:chrome:bidi-only 等测试脚本表明，BiDi 是独立于 CDP 的一套完整测试套件，可在 Chrome 上专项验证。

Puppeteer 默认以 headless 模式运行，即不弹出可见的浏览器窗口。对于无 UI 的服务器环境，这通常是期望行为；需要可视化调试时可通过启动参数调整（详见 docs/api/puppeteer.launchoptions.md 中 launch 的选项说明）。

安装

两种安装方式：puppeteer 与 puppeteer-core

README.md 给出的安装命令如下：

npm i puppeteer # 安装时会自动下载兼容版本的 Chrome
npm i puppeteer-core # 或者仅作为库安装，不下载 Chrome

两者的核心区别在于：

包	职责	是否下载浏览器
puppeteer	完整发行版：API + 浏览器下载管理	是（默认下载 Chrome 及 chrome-headless-shell）
puppeteer-core	纯库：仅包含 API 与驱动逻辑	否，需要你自己提供浏览器可执行文件路径或另行安装

从源码结构看，puppeteer 包本身非常薄——packages/puppeteer/src/puppeteer.ts 中仅做了一件事：实例化 PuppeteerNode 并对外导出 connect、defaultArgs、executablePath、launch、trimCache、setFollowSymlinks 等入口 API，其余全部 export * from 'puppeteer-core'。也就是说，puppeteer-core 承载了全部浏览器驱动能力，而 puppeteer 在其上附加了 Node.js 环境专属的“浏览器自动下载”逻辑。

当前仓库版本信息（以 packages/puppeteer/package.json 为准）：

• 包版本：25.8.0，依赖同版本 puppeteer-core 与 @puppeteer/browsers 3.2.1；
• 运行时要求：node >= 22.12.0（engines 字段）；
• 模块形态：ESM（"type": "module"），并通过 exports 暴露 puppeteer/internal/* 子路径供安装脚本使用。

安装时浏览器是怎么下载下来的（源码调用链）

puppeteer 的 package.json 注册了 "postinstall": "node install.mjs"。完整链路如下：

1. packages/puppeteer/install.mjs 在 npm install 结束后执行，动态导入 puppeteer/internal/node/install.js 并调用 downloadBrowsers()。该脚本明确注释自己是公共 API 的一部分，puppeteer-core 不包含此步骤，但必要时可以手动运行它；
2. packages/puppeteer/src/node/install.ts 中的 downloadBrowsers() 读取配置后，为 chrome、chrome-headless-shell、firefox 三个浏览器各构造一个下载任务（除非对应 skipDownload 为真），任务通过 @puppeteer/browsers 的 install() 完成下载与解压，版本号取 configuration.version → PUPPETEER_REVISIONS[browser] → 'latest' 三级回退（PUPPETEER_REVISIONS 定义于 packages/puppeteer-core/src/revisions.ts）；
3. 下载失败时会抛出明确提示：Failed to set up <browser> v<version>! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.，并在汇总失败时建议运行 npx puppeteer browsers install 重试，或先 npx puppeteer browsers clear 清理残缺缓存；
4. 该脚本还会用 npm 的代理配置（npm_config_https_proxy 等）覆盖 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量，保证内网代理环境下下载可用。

安装脚本被包管理器阻断时的补救

现代包管理器（npm、pnpm、Yarn、Bun、Deno）默认阻断依赖的安装脚本。README 特别警告：如果 install 脚本被阻断，Puppeteer 不会在安装期间下载浏览器，从而导致运行时报错。两种补救方式：

方式一：安装后手动下载浏览器

npx puppeteer browsers install

方式二：允许该包运行安装脚本（以 npm 为例，在 package.json 的 allowScripts 中加入 "puppeteer"）。

npx puppeteer browsers 的实现在 packages/puppeteer/src/node/cli.ts：它包装了 @puppeteer/browsers 的 CLI，把 browsers 作为子命令前缀（即 npx puppeteer browsers install|clear|list），并根据 Puppeteer 自身配置注入 pinnedBrowsers——把 chrome、firefox、chrome-headless-shell 的构建版本钉到 config.version 或 PUPPETEER_REVISIONS 对应值上，同时读取各浏览器的 skipDownload 配置（注意 firefox 的 CLI 默认 skip 为 true）。这与 packages/browsers/README.md 中直接调用 npx @puppeteer/browsers 的通用 CLI 用法互为表里，后者还额外支持：

npx @puppeteer/browsers install --help    # 查看 install 命令帮助
npx @puppeteer/browsers list              # 列出已安装浏览器
npx @puppeteer/browsers clear             # 清空所有已安装浏览器
npx @puppeteer/browsers install chrome@stable           # 下载 Stable 渠道的 Chrome for Testing
npx @puppeteer/browsers install chrome@116.0.5793.0      # 下载指定版本
npx @puppeteer/browsers install chromedriver@canary      # 下载 Canary 渠道的 ChromeDriver
npx puppeteer browsers install chrome --install-deps      # Ubuntu/Debian 上连带安装系统依赖（需 root）

browsers CLI 的系统要求（同样见 packages/browsers/README.md）：Firefox 下载在 Linux 需要 xz 与 bzip2、macOS 需要 hdiutil；Chrome 下载在 Linux/macOS 需要 unzip、Windows 需要 tar.exe。调试下载问题时可用 env NODE_DEBUG="puppeteer:browsers:*" npx @puppeteer/browsers install chrome@stable 打开 cache/fileUtil/install/launcher 四个调试通道。

跳过下载与自定义浏览器：环境变量与配置文件

puppeteer 包通过 packages/puppeteer/src/getConfiguration.ts 中的 getConfiguration() 汇总配置，优先级为：环境变量 > 配置文件 > 默认值。配置文件由 lilconfig 按以下搜索顺序查找：package.json（puppeteer 字段）、.config/puppeteer.config.cjs|js、.config/puppeteerrc*、.puppeteerrc*、puppeteer.config.cjs|js。仓库根目录的 puppeteer.config.js 就是一个实例——它将三个浏览器的 skipDownload 全部设为 false，表明开发仓库自身每次安装都下载全部浏览器。

关键配置项与对应环境变量如下（从 getConfiguration.ts 的解析逻辑归纳）：

环境变量	配置文件字段	说明
PUPPETEER_SKIP_DOWNLOAD	skipDownload	为真值时完全跳过浏览器下载；布尔解析接受 ''/0/false/off 为假，其余为真
PUPPETEER_EXECUTABLE_PATH	executablePath	指向系统/自定义浏览器可执行文件；一旦设置，源码会强制 skipDownload = true
PUPPETEER_BROWSER	defaultBrowser	默认浏览器，仅接受 chrome 或 firefox，否则抛出 Unsupported browser
PUPPETEER_CACHE_DIR	cacheDirectory	浏览器缓存目录，默认为 ~/.cache/puppeteer
PUPPETEER_TMP_DIR	temporaryDirectory	临时目录
PUPPETEER_LOGLEVEL	logLevel	日志级别 silent / error / warn（非法值回退为 warn）
PUPPETEER_CHROME_VERSION、PUPPETEER_CHROME_DOWNLOAD_BASE_URL、PUPPETEER_CHROME_SKIP_DOWNLOAD（以及 PUPPETEER_FIREFOX_*、PUPPETEER_CHROME_HEADLESS_SHELL_*）	chrome / firefox / chrome-headless-shell 对象下的 version / downloadBaseUrl / skipDownload	按浏览器粒度覆盖版本号与下载地址

一个典型的“使用系统 Chrome、不下载浏览器”的配置文件写法：

// puppeteer.config.js
export default {
  executablePath: '/usr/bin/google-chrome',
  // 也可显式写 skipDownload: true（设置 executablePath 后会自动置为 true）
};

另外两点值得注意：

• firefox 的默认配置中 skipDownload 为 true（见 getConfiguration() 中 getBrowserSetting('firefox', configuration, {skipDownload: true})），即默认只下载 Chrome 与 chrome-headless-shell，需要 Firefox 时须在配置中显式打开；
• 使用 PUPPETEER_EXECUTABLE_PATH 跳过下载后，launch 启动的就是你指定的浏览器，因此其版本必须与当前 Puppeteer 的协议能力匹配，跨版本兼容性需要自行保证。

第一个自动化示例

以下是 README.md 的完整示例代码，它演示了 launch、导航、视口设置、键盘操作、基于可访问性名称的定位与断言取值：

import puppeteer from 'puppeteer';
// Or import puppeteer from 'puppeteer-core';

// Launch the browser and open a new blank page.
const browser = await puppeteer.launch();
const page = await browser.newPage();

// Navigate the page to a URL.
await page.goto('https://developer.chrome.com/');

// Set the screen size.
await page.setViewport({width: 1080, height: 1024});

// Open the search menu using the keyboard.
await page.keyboard.press('/');

// Type into search box using accessible input name.
await page.locator('::-p-aria(Search)').fill('automate beyond recorder');

// Wait and click on first result.
await page.locator('.devsite-result-item-link').click();

// Locate the full title with a unique string.
const textSelector = await page
  .locator('::-p-text(Customize and automate)')
  .waitHandle();
const fullTitle = await textSelector?.evaluate(el => el.textContent);

// Print the full title.
console.log('The title of this blog post is "%s".', fullTitle);

await browser.close();

示例中有几个值得展开的技术点：

• launch() 是异步工厂：调用后会启动一个独立的浏览器进程（headless 默认），返回 Browser 实例，可用方法见 docs/api/puppeteer.browser.md；
• Locator 优先的交互模型：page.locator() 返回的 Locator 自带自动等待与重试，fill/click 等操作无需手动 waitForSelector。选择器语法除 CSS 外，还支持仓库内置的自定义查询 ::-p-aria(名称)（按可访问性名称匹配）与 ::-p-text(文本)（按文本内容匹配）；
• evaluate 进入页面上下文：textSelector?.evaluate(el => el.textContent) 在页面内读取 DOM 文本，? 处理了 waitHandle() 可能返回 undefined（元素未出现）的情况。Locator 各方法的完整签名见 docs/api/puppeteer.locator.md。

除 README 示例外，examples/ 目录提供了更多可运行脚本，例如 examples/screenshot.js、examples/pdf.js、examples/search.js、examples/cross-browser.js、examples/block-images.js（请求拦截）、examples/proxy.js，以及浏览器环境运行与扩展场景的 examples/puppeteer-in-browser/ 和 examples/puppeteer-in-extension/ 子项目，适合作为不同需求的起步模板。

MCP 与 WebMCP 集成

README.md 的 MCP 一节指出两个集成方向：

1. chrome-devtools-mcp：一个基于 Puppeteer 的 MCP（Model Context Protocol）服务器，用于面向 AI Agent 的浏览器自动化与调试。在 Agent 工具链中安装该 MCP 服务器后，模型即可通过标准 MCP 协议驱动 Puppeteer 完成页面操作。
2. WebMCP 实验性 API：Puppeteer 内置了 WebMCP 支持，允许网页侧向自动化端暴露工具。对应类型定义可在 docs/api/puppeteer.webmcp.md、docs/api/puppeteer.webmcptool.md、docs/api/puppeteer.webmcptoolcall.md 中查到，页面侧 API 入口为 page.webMcp，可读取 tools 列表并调用 execute。该能力仍标记为实验性，生产使用前建议确认所依赖版本的稳定状态。

仓库结构与进一步阅读

以 README 为主线，当前仓库中与“安装 + 上手”最相关的资源如下：

路径	内容
README.md	项目总览：定义、安装、MCP、示例
packages/puppeteer/src/puppeteer.ts	puppeteer 包入口：导出 launch、connect 等公共 API
packages/puppeteer/src/getConfiguration.ts	配置解析：环境变量与配置文件的合并规则
packages/puppeteer/src/node/install.ts	downloadBrowsers()：安装期浏览器下载实现
packages/puppeteer/src/node/cli.ts	npx puppeteer browsers 子命令入口
packages/browsers/README.md	@puppeteer/browsers CLI 与编程 API 说明
docs/api/puppeteer.launch.md	launch 方法与完整选项（headless、protocol 等）
docs/webdriver-bidi.md	WebDriver BiDi 协议支持与差异
examples/	可运行示例脚本集合
test/TestSuites.json	测试套件定义（chrome/bidi/firefox 各组合）

从根目录 package.json 的 wireit 任务还可以看到，仓库用 test:chrome:bidi、test:chrome:headful、test:chrome:headless、test:chrome:shell、test:chrome:pipe、test:firefox:headful、test:firefox:headless 等细粒度套件验证同一套 API 在不同协议与模式下的行为——这也印证了 README 开头“通过 DevTools Protocol 或 WebDriver BiDi 控制 Chrome 或 Firefox”这一核心承诺并非口号，而是被测试矩阵逐条覆盖的工程事实。

适用前提小结：使用本仓库版本的 puppeteer 需要 Node.js >= 22.12.0；安装期浏览器下载依赖 npm 安装脚本（被阻断时用 npx puppeteer browsers install 补救）；firefox 需显式配置才参与下载；使用 executablePath 指定外部浏览器时请自行保证版本兼容。