Puppeteer Browser.process() 方法解析：如何获取并管理浏览器子进程

2026-09-04 13:56:26作者：晏闻田Solitary

在 Puppeteer 中，绝大多数使用场景都始于 puppeteer.launch()，而每一次 launch 都会在当前 Node.js 进程之外派生出一个真实的浏览器操作系统进程。Browser.process() 是暴露这一底层关系的 API：它让你拿到与 Browser 实例关联的 Node.js ChildProcess 对象，从而可以读取进程 ID、监听退出事件、做资源诊断甚至手动终止进程。读完本文，你将理解 process() 的签名与返回语义、它在 launch 与 connect 两种模式下为何行为不同，以及它在 Puppeteer 源码中是如何被注入和传递的。

API 定义与返回值语义

Browser.process() 是 Browser 类上的一个抽象方法，用于获取关联的 ChildProcess 对象（Node.js child_process 模块中的 ChildProcess 类）。其签名如下：

class Browser {
  abstract process(): ChildProcess | null;
}

返回值：ChildProcess | null。当该 Browser 实例是通过 Puppeteer.connect() 连接到一个已经运行的浏览器时，返回 null——因为连接模式并不由 Puppeteer 负责派生进程，Puppeteer 无从持有对应的子进程句柄。

这一契约在仓库的抽象基类中有明确定义，见 Browser.ts：

  /**
   * Gets the associated
   * {@link https://nodejs.org/api/child_process.html#class-childprocess | ChildProcess}.
   *
   * @returns `null` if this instance was connected to via
   * {@link Puppeteer.connect}.
   */
  abstract process(): ChildProcess | null;

实现：CDP 与 BiDi 两条协议路径

Puppeteer 的 Browser 抽象类有两个主要实现，分别对应 Chrome DevTools Protocol（CDP）和 WebDriver BiDi 协议，两者对 process() 的实现模式完全一致：将进程句柄保存在私有字段中，调用时做空值归一。

CDP 实现见 cdp/Browser.ts：

  override process(): ChildProcess | null {
    return this.#process ?? null;
  }

其中 #process 是一个可选私有字段（#process?: ChildProcess），在构造函数中通过形参 process: ChildProcess | undefined = undefined 注入并保存（this.#process = process，见 cdp/Browser.ts）。BiDi 实现同理，见 bidi/Browser.ts：

  override process(): ChildProcess | null {
    return this.#process ?? null;
  }

注意这里的细节：内部字段是 undefined 而非 null，对外统一归一为 null。因此调用方只需要按文档描述的两种情况处理返回值即可。

进程句柄从哪里来：launch 路径的注入链

process() 之所以在 launch() 后非空，是因为浏览器进程由 Puppeteer 的启动器直接派生。从源码结构看，整条链路如下：

PuppeteerNode.launch()（见 PuppeteerNode.ts）解析启动选项，最终交由浏览器启动器派生浏览器进程；
启动器在 BrowserLauncher.ts 和 BrowserLauncher.ts 中，将派生出的 browserProcess.nodeProcess（即 Node 的 ChildProcess）作为 process 参数传入浏览器构造函数：

// BrowserLauncher.ts（CDP 分支与 BiDi 分支各有一处，逻辑一致）
process: browserProcess.nodeProcess,
defaultViewport: opts.defaultViewport,
acceptInsecureCerts: opts.acceptInsecureCerts,

该参数经构造函数存入 #process 字段，随后 browser.process() 即可随时取回。

与之相对，连接路径不会派生任何进程。PuppeteerNode.connect() 的实现非常简洁（见 PuppeteerNode.ts）：

  override connect(options: ConnectOptions): Promise<Browser> {
    options.logger ??= debug;
    return super.connect(options);
  }

连接模式下没有 ChildProcess 可传，构造函数收到的是 undefined，于是 process() 返回 null——这正是文档中"通过 Puppeteer.connect() 连接时返回 null"这一条言行的来源。

拿到 ChildProcess 之后能做什么

由于返回值就是标准 Node.js ChildProcess，Node 侧的全部进程能力都对你开放。典型用法：

1. 读取进程 ID，用于日志关联或外部监控：

const browser = await puppeteer.launch();
const childProcess = browser.process();
if (childProcess) {
  console.log('浏览器进程 PID:', childProcess.pid);
}

2. 监听退出事件，感知非正常崩溃：

browser.process()?.once('exit', (code, signal) => {
  console.log(`浏览器进程退出，code=${code}，signal=${signal}`);
});

这比仅依赖 browser.close 的解析更底层，能在浏览器进程被系统 OOM 或其他原因杀死时第一时间获知。

3. 手动终止进程。 优雅关闭应使用 await browser.close()，它会通过协议通知浏览器并等待进程正常退出；而 browser.process()?.kill() 则是更强制的手段，直接向操作系统发送信号，适用于浏览器已无响应、协议层 close() 挂死的兜底场景。使用时请注意：对 connect() 拿到的实例调用前必须判空，因为返回的是 null。

4. 资源诊断。 结合 pid 可以用系统工具检查浏览器进程的内存占用与句柄数量，辅助排查长时间运行场景下的资源泄漏。

注意事项与适用前提

必须判空：无论你的代码走的是 launch 还是 connect，调用 browser.process() 后都应当做 null 检查再使用，这是文档明确声明的契约。
平台依赖：ChildProcess 是 Node.js 概念，因此 process() 只在 Node 环境下有意义；Puppeteer 的浏览器端用法拿不到操作系统进程句柄。
launch 模式下几乎总是非空：只要由 Puppeteer 自己派生了浏览器进程，process() 就返回对应 ChildProcess；仅外部连接（connect()）会返回 null。
该行为在当前仓库的 CDP 与 BiDi 两个实现中一致，可放心跨协议使用。