Puppeteer 浏览器启动深度指南：PuppeteerNode.launch() 方法与 LaunchOptions 全解

本指南围绕 Puppeteer（一个通过 DevTools/WebDriver BiDi 协议驱动 Chrome 与 Firefox 的 Node 库）中负责"启动浏览器实例"的核心入口 PuppeteerNode.launch() 展开。它是每个 Puppeteer 自动化脚本的起跑线——掌握其签名、参数默认值与底层调用链，你就能稳定、可控地拉起 Chrome for Testing、系统 Chrome/Firefox，并在 puppeteer 与 puppeteer-core 两种包形态间正确切换。读完本文，你将能精确配置 headless、channel、executablePath、ignoreDefaultArgs、timeout 等关键选项，并理解启动失败的常见根因。

一、方法签名：launch() 是什么

launch() 是 PuppeteerNode 类 上最常用的方法。所谓 PuppeteerNode，是在通用 Puppeteer 基类之上，扩展了"获取与下载浏览器"等 Node 特有行为的类（源码位于 PuppeteerNode.ts）。

官方 API 文档给出的签名如下：

class PuppeteerNode {
  launch(options?: LaunchOptions): Promise<Browser>;
}

• 参数 options?：类型为 LaunchOptions，可选，用于配置启动行为；
• 返回值：Promise<Browser>，解析为一个已连接好的 Browser 实例。

触发条件上的硬性差异：puppeteer vs puppeteer-core

文档特别强调一条极易踩坑的规则：

当配合 puppeteer-core 使用时，必须提供 options.executablePath 或 options.channel。

原因在于两者的默认行为不同（可对比源码入口 puppeteer.ts 与 puppeteer-core 的实例化逻辑）：

• puppeteer：安装时默认下载与当前版本匹配的 Chrome for Testing，launch() 无需任何参数即可启动内置浏览器，同时还能读取项目配置文件（puppeteer.config.js）中的 cacheDirectory、defaultBrowser 等设置；
• puppeteer-core：不携带、不下载任何浏览器，也没有配置文件配套逻辑，因此它"不知道去哪里找可执行文件"，必须由你显式给出 channel（去系统已知位置找 Chrome）或 executablePath（指定某个浏览器可执行文件的具体路径）。

一个最小可运行的典型示例

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();      // 零配置：启动 Puppeteer 自带/缓存的 Chrome for Testing
const page = await browser.newPage();
await page.goto('https://www.google.com');
// ...对页面执行点击、截图、抓取等操作
await browser.close();                         // 记得关闭，释放进程资源

拿到 page 后，就可以使用 Page 文档 中列出的大量交互 API（跳转、点击、查找元素等）。

二、LaunchOptions 参数全表：每个选项的含义与默认值

LaunchOptions 扩展自 ConnectOptions，是"启动任意浏览器"的通用选项集合。下表完整列出所有字段（类型、默认值均以当前仓库文档与源码 LaunchOptions.ts 为准）：

属性	类型	说明	默认值
args	string[]	追加传递给浏览器实例的额外命令行参数	—
browser	SupportedBrowser	启动哪个浏览器	'chrome'
channel	ChromeReleaseChannel	若指定，则在系统已知位置查找常规 Chrome 安装，而非使用自带 Chrome 二进制	—
debuggingPort	number	指定调试端口号	—
devtools	boolean	是否为每个标签页自动打开 DevTools 面板；为 true 时会强制 headless 为 false	false
dumpio	boolean	为 true 时把浏览器进程的 stdout/stderr 管道到 process.stdout/process.stderr	false
enableExtensions	boolean | string[]	为 true 时避免传入会阻止扩展生效的默认参数；传入字符串数组则会按给定路径加载未打包扩展	—
env	Record<string, string | undefined>	指定对浏览器可见的环境变量	取 process.env
executablePath	string	指定要使用的浏览器可执行文件路径，替代自带浏览器。Puppeteer 只保证与自带浏览器兼容，使用有风险；建议同时设置 browser 属性	—
extensionsEnabledInIncognito	string[]	将在隐身/离席（off-the-record）配置文件中启用的扩展列表	—
extraPrefsFirefox	Record<string, unknown>	使用 Firefox 启动时可传入的额外偏好设置	—
handleSIGHUP	boolean	收到 SIGHUP 时关闭浏览器进程	true
handleSIGINT	boolean	按 Ctrl+C 时关闭浏览器进程	true
handleSIGTERM	boolean	收到 SIGTERM 时关闭浏览器进程	true
headless	boolean | 'shell'	是否以无头模式运行浏览器	true
ignoreDefaultArgs	boolean | string[]	为 true 时不使用 puppeteer.defaultArgs()；为数组时则过滤掉这些默认参数	false
pipe	boolean	通过管道而非 WebSocket 连接浏览器，仅 Chrome 支持	false
signal	AbortSignal	提供后，信号被中止时关闭浏览器	—
timeout	number	等待浏览器启动的最大毫秒数，传 0 禁用超时	30000（30 秒）
userDataDir	string	用户数据目录路径	—
waitForInitialPage	boolean	是否等待初始页面就绪；当你显式禁用初始页面（如 Chrome 的 --no-startup-window）时很有用	true

注意其中的联动关系：devtools: true 会把 headless 强制为 false；pipe 与 debuggingPort 在同一启动中不可同时使用（源码中会直接断言报错："Browser should be launched with either pipe or debugging port - not both."，见 ChromeLauncher.ts）。

三、headless：新无头模式与 "shell" 旧无头模式

headless 是日常使用频率最高的选项之一。文档给出的语义是：

• headless: true：以**新无头模式（new headless）**启动浏览器，即当前 Chrome/Chrome for Testing 对 Chrome 团队所倡导的无头运行方式，与有头模式共享同一套 Chromium 渲染路径，特性支持最完整；
• headless: 'shell'：启动 Chrome Headless Shell（即旧无头模式独立产物 chrome-headless-shell），适用于仅需基础截图/打印等轻量场景、希望占用更小资源的用户；
• headless: false：启动有头（headful）浏览器，可看见真实窗口，便于调试交互。

从实现看，该选项还会影响"解析可执行文件路径"的结果：源码 BrowserLauncher.ts 的映射逻辑表明，当 browser === 'chrome' 且 headless === 'shell' 时，Puppeteer 会去寻找 CHROMEHEADLESSSHELL 二进制而非完整版 Chrome。单元测试 PuppeteerNode.test.ts 也验证了 executablePath({ headless: 'shell' }) 会返回包含 chrome-headless-shell 的路径。

// 新无头（默认等价形式）
const browser = await puppeteer.launch({ headless: true });

// 旧无头 shell，占用更小
const browser = await puppeteer.launch({ headless: 'shell' });

// 有头模式，肉眼可见窗口
const browser = await puppeteer.launch({ headless: false });

四、ignoreDefaultArgs：过滤默认参数的两种用法

Puppeteer 在启动浏览器时会自动追加一批"稳妥默认参数"（puppeteer.defaultArgs() 的产物，通常包括 --no-startup-window、--mute-audio、--disable-extensions 等）。ignoreDefaultArgs 允许你精细控制这批参数：

• true：完全弃用默认参数，风险很高——源码注释也提醒"你大概率还是需要 Puppeteer 的默认参数，请谨慎使用"；
• string[]：仅剔除数组中列出的那几个默认参数，其余保留。

原文档给出的过滤示例（去掉默认参数 --mute-audio，常用于希望保留浏览器音频输出的爬虫/采集场景）：

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--mute-audio'],
});

对照源码实现可以看到这个选项的准确行为（ChromeLauncher.ts）：当 ignoreDefaultArgs 为数组时，会先取 this.defaultArgs(options)，再按数组逐项 filter 掉匹配项；当它是 true 时，则完全跳过默认参数、只保留你通过 args 传入的内容。

五、选择浏览器来源：channel、executablePath 与 Chrome for Testing

官方文档在 Remarks 中对浏览器兼容性给出了明确的边界声明，值得原样理解：

Puppeteer 也可用于控制 Chrome 浏览器，但它与默认下载的 Chrome for Testing配合效果最佳；不保证能与其他任何版本正常工作。若你更愿意使用 Google Chrome（而非 Chrome for Testing），官方建议采用 Chrome Canary 或 Dev Channel 构建，而不是稳定版。Chrome 是闭源二进制、Chromium 是其开源上游，两者在稳定性、编解码器与发行策略上均有差异。

（关于 Chrome、Chromium 与 Chrome for Testing 三者的渊源差异，可参见 Chromium 官方博客对 Chrome for Testing 的说明以及 Chromium vs Chrome 的对比资料，本文不再展开外部链接。）

Chrome for Testing 是什么？ 它是专为自动化测试而发布的 Chrome 构建：固定版本、可直接下载、默认关闭自动更新，避免"今天能跑、明天升级后 API 变了"的经典自动化噩梦。这是 puppeteer 包在 npx puppeteer browsers install chrome（或安装期脚本）之后默认使用并成功概率最高的目标。

落实到 launch() 参数上，两种指定"外部浏览器"的方式是：

// 方式一：channel —— 使用系统已知位置安装的 Chrome 发布渠道
const browser = await puppeteer.launch({ channel: 'chrome' });        // 稳定版
const browser = await puppeteer.launch({ channel: 'chrome-beta' });   // Beta
const browser = await puppeteer.launch({ channel: 'chrome-dev' });    // Dev
const browser = await puppeteer.launch({ channel: 'chrome-canary' }); // Canary

// 方式二：executablePath —— 显式指向某个可执行文件（puppeteer-core 必备）
const browser = await puppeteer.launch({
  executablePath: '/usr/bin/google-chrome',  // 请替换为实际路径
  browser: 'chrome',                         // 建议同时显式指定 browser
});

channel 值会被转换为 browsers 包内部的发布渠道枚举（STABLE/BETA/DEV/CANARY），转换逻辑见 LaunchOptions.ts。使用 executablePath 时，源码建议同时设置 browser 属性，因为 Puppeteer 默认按 chrome 处理。

launch() 对 Firefox 同样适用，且默认走 WebDriver BiDi 协议；通过 extraPrefsFirefox 可向其传入 Firefox 偏好项。

六、源码级启动链路：launch() 背后发生了什么

launch() 本身并不复杂，真正的工作由它委托给浏览器专用 Launcher 完成。阅读源码有助于定位问题时给出准确判断。

第一步：PuppeteerNode.launch 的参数归一化

PuppeteerNode.ts 中的实现要点：

async launch(options: LaunchOptions = {}): Promise<Browser> {
  options.logger ??= debug;
  const {browser = await this.defaultBrowser()} = options;   // 默认浏览器取自配置
  this.#lastLaunchedBrowser = browser;
  if (!['chrome', 'firefox'].includes(browser)) {
    throw new Error(`Unknown product: ${browser}`);          // 非法 product 直接抛错
  }
  this.#launcher = this.#getLauncher(browser, options.logger);
  return await this.#launcher.launch(options);
}

几个值得注意的推断点：

• 未显式传 browser 时，会先调用 defaultBrowser()——它读取 Puppeteer 配置中的 defaultBrowser 字段，未配置则回落到 'chrome'（PuppeteerNode.ts）；
• browser 只接受 'chrome' / 'firefox'，传入其他字符串会抛出 Unknown product 错误；
• #getLauncher 会按浏览器类型惰性缓存 Chrome/Firefox 各自的 Launcher 实例：chrome → ChromeLauncher，firefox → FirefoxLauncher（同段源码 L150-L162）。

第二步：BrowserLauncher.launch 组装真实启动

ChromeLauncher.launch 继承并调用抽象基类 BrowserLauncher.launch（BrowserLauncher.ts），其核心流程可概括为：

1. 解构并填充大量默认值：timeout 默认 30000、waitForInitialPage 默认 true、handleSIG* 三个信号处理默认 true、env 默认 process.env、defaultViewport 等；
2. 协议选择：Firefox 未显式指定 protocol 时默认 'webDriverBiDi'；并显式禁止"Firefox + CDP"组合（否则抛错 "Connecting to Firefox using CDP is no longer supported"）；
3. 计算启动参数：调用 computeLaunchArguments()，合并默认参数、--remote-debugging-port/--remote-debugging-pipe 与临时 --user-data-dir（无自定义目录时用 mkdtemp 创建临时 profile 目录）；
4. 校验可执行文件存在：launchArgs.executablePath 不存在时会抛出包含明确路径的错误，并提示可能原因——未先执行 npx puppeteer browsers install chrome、或缓存目录配置不正确；
5. 真正拉起进程：调用 @puppeteer/browsers 包的 launch()，并按 dumpio 决定是否透传 stdout/stderr；
6. 建立协议连接：Chrome 走 CDP——pipe: true 用 PipeTransport，否则等待浏览器输出 WebSocket endpoint 后建立 NodeWebSocketTransport；Firefox 则等待 WebDriver BiDi endpoint；
7. 收尾：若是 enableExtensions 传入路径数组，则逐个 installExtension 加载扩展；随后若 waitForInitialPage，等待第一个 page 类型 target 出现后才 resolve（waitForPageTarget），期间任何失败都会调用 closeCallback 清理临时用户目录。

这套链路也解释了文档中 timeout、waitForInitialPage、handleSIGHUP/SIGINT/SIGTERM 等"进程生命周期"选项为何如此设计——它们分别对应启动等待、初始页等待与进程信号接管三个阶段。

第三步：典型报错与根因速查

报错特征	常见根因	对应源码/文档位置
Unknown product: xxx	browser 传了 chrome/firefox 之外的值	PuppeteerNode.ts
Browser was not found at the configured executablePath	配置/传参指向的二进制不存在	BrowserLauncher.ts
Could not find Chrome (ver. ...)	未执行浏览器安装或 cache 目录配置错误	BrowserLauncher.ts
The browser is already running for ...	同一 userDataDir 已有实例占用（Profile 单例冲突）	BrowserLauncher.ts
Missing X server ...	无显示器环境下设置了 headless: false	BrowserLauncher.ts
Browser should be launched with either pipe or debugging port - not both.	同时使用 pipe 与 debuggingPort	ChromeLauncher.ts

七、实战组合示例

示例 1：CI 无头截图 + 自定义视口 + 超时保护

const browser = await puppeteer.launch({
  headless: true,
  timeout: 60_000,                    // 慢网络环境下放宽启动等待
  args: ['--no-sandbox', '--disable-setuid-sandbox'], // 容器/CI 常见需要
});
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800 });
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'home.png' });
await browser.close();

示例 2：puppeteer-core + 系统 Chrome

import puppeteer from 'puppeteer-core';   // 注意包名

const browser = await puppeteer.launch({
  channel: 'chrome',                     // 或提供 executablePath
  headless: false,                       // 有头便于人工观察
});
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

示例 3：AbortSignal 优雅退出与诊断输出

const controller = new AbortController();

const browser = await puppeteer.launch({
  signal: controller.signal,             // abort 时自动关闭浏览器
  dumpio: true,                          // 便于观察浏览器进程日志定位问题
});

setTimeout(() => controller.abort(), 10_000);

八、延伸：与 launch 相邻的 PuppeteerNode 能力

理解了 launch()，不妨顺带掌握它身边的同类方法（PuppeteerNode 类文档）：

• connect()：挂接到一个已存在的浏览器实例（多用于复用外部启动的浏览器/远程调试场景），与 launch 正好互补；
• defaultArgs()：返回浏览器将被启动时的默认参数，配合 ignoreDefaultArgs 做参数裁剪前可先查看输出；
• defaultBrowser()：返回默认启动的浏览器名，puppeteer 下受配置影响，否则为 chrome；
• executablePath()：按渠道、LaunchOptions 或默认三种重载返回可执行文件路径；
• lastLaunchedBrowser()：返回最近一次启动的浏览器名；
• trimCache()：清理缓存目录中非当前版本的 Firefox/Chrome 二进制。

若需进一步了解启动后的页面自动化能力，可继续阅读 Page 文档；需要全局配置（缓存目录、默认浏览器、浏览器版本等）时，可参考 Configuration 文档 与仓库根目录的 puppeteer.config.js。相关单元测试见 PuppeteerNode.test.ts，它直接以 new PuppeteerNode({...}) 注入内存缓存目录来验证 executablePath 与 defaultArgs 的行为，可作为理解该类语义的最短代码范例。