@puppeteer/browsers 浏览器进程启动配置全面指南：LaunchOptions 接口逐字段解析与实战

@puppeteer/browsers 是 Puppeteer 仓库中负责「浏览器/驱动下载、缓存与进程托管」的独立子包。其中 launch() 函数负责真正把一个可执行文件拉起成子进程，而它的唯一入参类型正是 LaunchOptions 接口。本文以 LaunchOptions 接口文档 为骨架，结合 launch.ts 源码、Process 类文档 与三套（Chrome / Chromium / Firefox）启动测试用例，逐字段讲清每个配置项的语义、默认值、底层实现，以及如何用它在自己的 Node 程序里以编程方式、或在命令行中稳定地启动一个自动化浏览器进程。读完你将能独立编写「安装 → 计算可执行路径 → 按需配置 → 启动 → 生命周期清理」的完整链路代码。

一、接口定位：launch() 的唯一入参

LaunchOptions 在 browsers.launchoptions.md 中的声明非常简单：

export interface LaunchOptions

它被 launch() 函数 用作唯一入参：

export declare function launch(opts: LaunchOptions): Process;

而 Process 类 是对「浏览器子进程」的对象化封装：它包装了 Node.js 的 child_process.ChildProcess（可通过只读属性 nodeProcess 访问），并提供 close()、kill()、hasClosed()、getRecentLogs()、waitForLineOutput(regex, timeout) 等进程级控制与日志方法。

也就是说，LaunchOptions 是「把哪些参数以什么方式交给哪个可执行文件、以及如何托管其生命周期」的全部决策点。从源码看，launch.ts 的实现只是把选项转发给 Process 构造函数：

export function launch(opts: LaunchOptions): Process {
  return new Process({
    ...opts,
    logger: opts.logger ?? debug,
  });
}

未指定 logger 时，会默认使用 debug（基于 Node 内建 debuglog 机制），对应调试通道前缀 puppeteer:browsers:launcher（见 debug.ts）。

二、LaunchOptions 全部属性速览

接口共定义 11 个属性，除 executablePath 为必填外其余全部可选。下表汇总了每个字段的类型、说明与默认值（默认值以官方 API 文档为准）：

属性	修饰符	类型	说明	默认值
args	optional	string[]	启动时额外传给可执行文件的参数	—
detached	optional	boolean	是否以 Node.js 的 detached 模式派生子进程	true（Windows 除外）
dumpio	optional	boolean	为 true 时把浏览器进程的 stdout/stderr 转发到 Node 进程的 stdout/stderr	false
env	optional	Record<string, string | undefined>	为浏览器进程设置的环境变量	—
executablePath	必填	string	浏览器可执行文件的绝对路径	—
handleSIGHUP	optional	boolean	在 Node 进程收到 SIGHUP 时接管，尝试优雅关闭浏览器进程	true
handleSIGINT	optional	boolean	在 Node 进程收到 SIGINT 时接管，尝试杀掉浏览器进程	true
handleSIGTERM	optional	boolean	在 Node 进程收到 SIGTERM 时接管，尝试优雅关闭浏览器进程	true
logger	optional	Logger	用自定义 logger 替换默认内部 logger	—
onExit	optional	() => Promise<void>	浏览器进程退出后、或经由 Process.close()（含信号处理）即将关闭前执行的回调，只执行一次	—
pipe	optional	boolean	将 stdio 配置为额外打开两条流，改为通过流进行自动化而非 WebSocket	false
signal	optional	AbortSignal	提供后，信号被 abort 时进程将被杀掉	—

下面逐组深入剖析。

三、必填项：executablePath 与 args

3.1 executablePath —— 可执行文件绝对路径

executablePath: string 是接口中唯一没有标 optional 的必填属性。它必须是浏览器可执行文件的绝对路径。通常你不必手写该路径，而是通过 computeExecutablePath() 从缓存目录解析：

import {computeExecutablePath, Browser} from '@puppeteer/browsers';

const executablePath = computeExecutablePath({
  cacheDir: '/tmp/puppeteer-browsers-test',
  browser: Browser.CHROME,
  buildId: '123',
});

Chrome 启动测试 展示了缓存目录与平台相关的路径推算规律：对 Linux + Chrome，结果形如 path.join('.cache', 'chrome', 'linux-123', 'chrome-linux64', 'chrome')；Chromium 与 Firefox 测试（chromium/launch.test.ts、firefox/launch.test.ts）则分别得到 chrome-linux/chrome 与 firefox/firefox 的目录结构。

从 launch.ts 源码可以看到，进程启动本质是一次标准的 child_process.spawn：

this.#browserProcess = childProcess.spawn(
  this.#executablePath,
  this.#args,
  {
    detached: opts.detached,
    windowsHide: true,
    env,
    stdio,
  },
);

注意源码还固定传了 windowsHide: true，保证在 Windows 上不会弹出黑色控制台窗口。

3.2 args —— 透传给二进制的命令行参数

args: string[] 会被原样拼在可执行文件后面传给浏览器（源码见 launch.ts，日志中形如 Launching <path> <args joined by space>）。

一个典型的 Chrome headless 自动化启动参数集，直接取自 chrome/launch.test.ts：

const args = [
  '--disable-background-networking',
  '--disable-background-timer-throttling',
  '--disable-extensions',
  '--disable-features=Translate,BackForwardCache,AcceptCHFrame,MediaRouter,OptimizationHints',
  '--disable-popup-blocking',
  '--disable-sync',
  '--enable-automation',
  '--force-color-profile=srgb',
  '--headless=new',
  '--metrics-recording-only',
  '--no-first-run',
  '--password-store=basic',
  '--remote-debugging-port=9222',
  '--use-mock-keychain',
  '--user-data-dir=/tmp/profile',
  'about:blank',
];

需要强调：args 是否包含 --headless、--remote-debugging-port 等，直接决定了浏览器是否真的「可被自动化连接」。在 CLI 中，launch 命令支持用 -- 之后的内容透传这些参数（见下文第六节）。

四、进程行为控制：pipe / dumpio / detached

4.1 pipe —— 通过 stdio 流自动化而非 WebSocket

pipe: boolean 为 true 时，configureStdio 会把 stdio 数组从默认的 3 条流（stdin/stdout/stderr）扩展为 5 条：

#configureStdio(opts: {pipe: boolean}): Array<'ignore' | 'pipe'> {
  if (opts.pipe) {
    return ['pipe', 'pipe', 'pipe', 'pipe', 'pipe'];
  } else {
    return ['pipe', 'pipe', 'pipe'];
  }
}

多出的两条流正是 Puppeteer 用于「基于管道（pipe）的自动化传输」的通道，用以替代 WebSocket。默认 false。

4.2 dumpio —— 把浏览器日志透传到终端

dumpio: boolean 为 true 时，浏览器子进程的 stdout 与 stderr 会被直接 pipe 到 Node 进程的 stdout/stderr（launch.ts）：

if (opts.dumpio) {
  this.#browserProcess.stderr?.pipe(process.stderr);
  this.#browserProcess.stdout?.pipe(process.stdout);
}

这在排障时非常有用：你能直接看到浏览器打印的 DevTools listening on ws://... 之外的完整原生输出。默认 false。

4.3 detached —— 是否脱离为新的进程组

detached: boolean 默认值为文档标注的 true（Windows 除外），对应 Node 的 child_process detached 选项。源码在构造函数中通过 opts.detached ??= true 兜底（launch.ts），并保留注释说明其意图：

detached: true 让子进程成为新进程组的组长，从而可以隔离进程树、阻止控制台信号传播。

这一设计影响深远：进程组隔离让后续 kill() 可以对「整个进程组」发信号，从而连浏览器派生的渲染子进程一起清理，避免僵尸进程残留。

五、环境与信号：env / signal / onExit / handleSIGxxx

5.1 env —— 浏览器进程的环境变量

env: Record<string, string | undefined> 用于设置浏览器子进程的环境变量。需要指出一个易踩坑点：child_process.spawn 的 env 选项是整体替换而非合并，源码中直接 const env = opts.env || {}; 后传给 spawn（launch.ts）。因此若你需要「继承系统环境并微调」，请先展开 process.env：

const process = launch({
  executablePath,
  args,
  env: {
    ...process.env,        // 先继承
    PUPPETEER_EXTRA_ENV: '1', // 再覆盖 / 新增
  },
});

另一个值得注意的实现细节：虽然完整 env 会传给子进程，但写入内部日志的只有以 puppeteer_ 前缀开头（大小写不敏感）的键，避免把敏感环境变量整个打印出来：

if (key.toLowerCase().startsWith('puppeteer_')) {
  res[key] = env[key];
}

5.2 signal —— 通过 AbortSignal 一键中止

signal: AbortSignal 提供后，浏览器进程会在信号被 abort 时被 kill()。构造函数中有两处处理（launch.ts）：

this.#signal = opts.signal;
if (this.#signal?.aborted) {
  throw new Error(
    this.#signal.reason ? this.#signal.reason : 'Launch aborted',
  );
}
this.#signal?.addEventListener('abort', this.#onAbort, {once: true});

也就是说：

• 若传入的 signal 已经处于 aborted 状态，launch() 会直接同步抛错（错误消息取自 signal.reason，缺省为 Launch aborted）；
• 若启动后中途 abort，则调用内部 kill()。

这一点在 chrome/launch.test.ts 中有两个用例验证：should throw if signal is already aborted 与 should kill the process when signal is aborted（后者会 await process.hasClosed() 等待进程真正结束）。配合 AbortController 或 AbortSignal.timeout()，你可以实现「超时强制回收浏览器」。

5.3 onExit —— 只执行一次的收尾回调

onExit: () => Promise<void> 是一个收尾钩子。文档语义是：在浏览器进程退出之后、或即将经由 Process.close()（含信号处理）关闭之前执行，且整个生命周期内只执行一次。

源码用 #hooksRan 标志位保证幂等（launch.ts），并在两处触发：

• Process.close() 被调用时先执行 #runHooks() 再决定是否 kill()（launch.ts）；
• 浏览器子进程触发 exit 事件时执行（launch.ts）。

典型用途是清理临时 profile、释放端口、上报埋点等一次性工作：

const process = launch({
  executablePath,
  args,
  onExit: async () => {
    await cleanupUserDataDir(); // 例如删除临时 --user-data-dir
  },
});

5.4 handleSIGINT / handleSIGTERM / handleSIGHUP —— 信号接管

三个开关都默认 true，控制 Node 宿主进程收到终端信号时如何连带处理浏览器进程：

信号	含义	接管后的动作
SIGINT	Ctrl+C 中断	调用 kill() 强杀浏览器进程，然后 process.exit(130)
SIGTERM	终止请求	调用 void this.close()（优雅关闭）
SIGHUP	终端挂断	调用 void this.close()（优雅关闭）

对应的分发逻辑见 launch.ts：

#onDriverProcessSignal = (signal: string): void => {
  switch (signal) {
    case 'SIGINT':
      this.kill();
      process.exit(130);
    case 'SIGTERM':
    case 'SIGHUP':
      void this.close();
      break;
  }
};

实现上，Process 通过 subscribeToProcessEvent 维护了一张全局事件处理器表，按事件类型复用同一个 Node process.on 监听（launch.ts），进程退出时由 #clearListeners() 统一退订（launch.ts），避免多个浏览器进程叠加监听、泄漏内存。

5.5 logger —— 替换默认内部日志器

logger: Logger 允许替换默认内部 logger。其类型签名（debug.ts）为：

export type LoggerFunction = (...args: unknown[]) => void;
export type Logger = (prefix: string) => LoggerFunction | undefined;

launch() 会以 DEBUG_PREFIXES.launcher（即 puppeteer:browsers:launcher）作为前缀调用 logger，并把每次调用返回的函数当作实际的日志输出函数；Process 构造函数通过 this.#logger = opts.logger?.(DEBUG_PREFIXES.launcher) 获得它。默认 logger 使用 Node 内建 debuglog，因此无需任何额外依赖即可通过环境变量开启详细日志：

env NODE_DEBUG="puppeteer:browsers:launcher" node your-script.mjs

若想在代码中看到「将要执行的可执行文件 + 参数 + detached/env/stdio 决策」，直接把 NODE_DEBUG=puppeteer:browsers:launcher 打开即可，这正是 packages/browsers/README.md 中列出的调试通道之一。

六、端到端实战：安装 → 定位 → 按需配置启动

把上面所有字段串起来，一个完整的程序化启动流程如下。它先安装浏览器、再解析可执行文件路径，最后用 LaunchOptions 里除默认项外的常用字段启动：

import {
  install,
  computeExecutablePath,
  launch,
  Browser,
} from '@puppeteer/browsers';

// 1. 安装（已在缓存中则幂等跳过）
await install({
  cacheDir: '/tmp/puppeteer-browsers-test',
  browser: Browser.CHROME,
  buildId: 'stable',          // 也支持显式版本号，如 '116.0.5793.0'
});

// 2. 计算绝对可执行路径
const executablePath = computeExecutablePath({
  cacheDir: '/tmp/puppeteer-browsers-test',
  browser: Browser.CHROME,
  buildId: 'stable',
});

// 3. 按需组装 LaunchOptions 并启动
const controller = new AbortController();
const proc = launch({
  executablePath,                              // 必填
  args: ['--headless=new', '--no-first-run',
         '--remote-debugging-port=9222',
         '--user-data-dir=/tmp/pb-profile'],   // 附加参数
  detached: true,                              // 独立进程组（便于整组清理）
  dumpio: false,                               // 调试期可临时设为 true
  pipe: false,                                 // 如需管道自动化改为 true
  env: {...process.env},                       // 继承宿主环境
  handleSIGINT: true,                          // 默认即 true，可显式声明
  handleSIGTERM: true,
  handleSIGHUP: true,
  signal: controller.signal,                   // 超时/取消用
  onExit: async () => {
    console.log('browser exited, cleanup here');
  },
});

// 4. 等待 DevTools WebSocket 端点出现在 stdout 中（CDP 自动化入口）
const wsEndpoint = await proc.waitForLineOutput(
  /^DevTools listening on (ws:\/\/.*)$/,   // 即导出的 CDP_WEBSOCKET_ENDPOINT_REGEX
  30_000,                                   // 30 秒超时
);
console.log('ws endpoint:', wsEndpoint);

// 5. 收尾：优雅关闭（会先跑 onExit 钩子）
await proc.close();

关于 waitForLineOutput：它监听浏览器 stdout 的每一行，用正则捕获 match[1] 作为结果（launch.ts）；若进程提前退出或超时，会 reject 并把最近日志连同 pptr.dev/troubleshooting 提示一并抛出。Chrome/Chromium 测试正是通过它解析出 ws://127.0.0.1:9222/devtools/browser/... 端点（chrome/launch.test.ts）。

辅助方法 getRecentLogs() 返回最近最多 1000 行（#maxLogLinesSize = 1000，见 launch.ts）的 stderr+stdout 记录，便于进程异常时回溯现场。

七、CLI 视角：launch 命令如何映射到 LaunchOptions

如果你不想写代码，@puppeteer/browsers 自带 CLI。launch <browser> 子命令（CLI.ts）最终等价于一次携带最小 LaunchOptions 的 launch() 调用：

launch({
  args: extraArgs,
  executablePath,
  dumpio: args.dumpio,
  detached: args.detached,
});

典型用法：

# 启动缓存中的指定版本 Chrome
npx @puppeteer/browsers launch chrome@115.0.5790.170

# 启动 Firefox 里程碑版本
npx @puppeteer/browsers launch firefox@112.0a1

# --detached 让子进程脱离独立运行
npx @puppeteer/browsers launch chrome@115.0.5790.170 --detached

# --system 改为定位系统已安装的 Canary 构建（走 computeSystemExecutablePath）
npx @puppeteer/browsers launch chrome@canary --system

# -- 之后的内容作为 args 透传给浏览器二进制
npx @puppeteer/browsers launch chrome@115.0.5790.170 -- --version

CLI 层面的映射关系可以理解为：executablePath 由 computeExecutablePath / computeSystemExecutablePath 自动推导（CLI.ts），--detached、--dumpio 直接对应同名选项，其余字段（env、pipe、signal、onExit、logger、三个 handleSIGxxx）则只在编程式 API 中开放——它们大多与进程生命周期托管相关，属于宿主进程代码的职责。

八、底层原理：Process 类的生命周期与跨平台清理

理解 LaunchOptions 各开关的最终效果，绕不开 Process 类 的实现。它的生命周期设计要点如下：

1. 构造函数即启动。所有默认值（pipe=false、dumpio=false、handleSIGINT/SIGTERM/SIGHUP=true、detached=true）在构造时通过 ??= 补齐（launch.ts），随即 spawn 子进程并注册宿主进程事件。

2. kill() 是跨平台的进程组清理（launch.ts）：

• Windows：优先用 taskkill /pid <pid> /T /F 连子进程树一起强杀，失败再退回 Node API；
• Linux/macOS：由于 detached 让浏览器成为进程组组长，可直接对负的进程组 ID 发 SIGKILL，把整个浏览器进程树（含 GPU/渲染等子进程）一网打尽；权限不足时再退回 child.kill('SIGKILL')。
• 进程不存在（pidExists 检测为 false，例如可执行文件路径非法导致启动失败）时静默跳过。

3. close() 先钩子后清理（launch.ts）：先 await #runHooks() 执行 onExit，再视情况 kill()，最后 await #browserProcessExiting 等待进程真正退出。测试中广泛使用的 await process.close()（如 chromium/launch.test.ts）正是依赖这条契约。

4. 信号处理的全局注册表：多个 Process 实例共享同一批 process.on 监听器，通过 Map 按事件分发，逐个实例退出时自动退订（#clearListeners），保证多浏览器场景下互不干扰且无监听器泄漏。

九、最佳实践小结

1. 永远优先 computeExecutablePath 而不是硬编码路径：配合 install 使用可保证「先装后用」，且路径规则已由 Cache 实现 与三个平台的启动测试锁定。
2. env 记得 ...process.env：spawn 的 env 是整表替换，忘记继承会导致浏览器缺少 HOME、PATH 等基础变量而异常。
3. 调试期开 dumpio 或 NODE_DEBUG=puppeteer:browsers:launcher，把浏览器原生 stdout/stderr 亮出来；排查启动失败可读取 process.getRecentLogs() 帮助定位。
4. 合理选择退出语义：需要立刻终止用 kill()（整进程组）；要优雅回收并确保 onExit 先执行，用 close()；需要响应宿主 Ctrl+C 则保留默认的 handleSIGINT: true（对应退出码 130）。
5. signal 与 AbortSignal.timeout() 组合可实现「启动超时即杀」，但要记得已 abort 的信号会让 launch() 同步抛错，先做一次 signal.aborted 判断更稳妥。

LaunchOptions 的设计哲学很清晰：把「启动什么（executablePath + args）、怎么启动（pipe / dumpio / detached / env）、何时结束（signal / onExit / handleSIGxxx）、如何观测（logger / dumpio）」四类关注点收敛到一个接口，再交由 Process 统一承载跨平台的进程树清理与生命周期保障。需要进一步查阅返回对象能力时，可继续阅读 Process 类、close()、waitForLineOutput() 与 launch() 函数 的 API 文档，并对照 packages/browsers/test/src 下的 Chrome / Chromium / Firefox 三套真实测试代码加深理解。