深入理解 Process.close()：Puppeteer @puppeteer/browsers 浏览器进程的优雅关闭

导读

Process.close() 是 @puppeteer/browsers 包中用于终止由 Node.js 拉起的浏览器子进程并等待其彻底退出的核心 API。本文以 Process.close() 官方 API 文档 为骨架，结合其所在的 Process 类文档 与仓库中 Process 类的源码实现，逐步剖析 close() 的签名、内部执行流程、与 kill() / hasClosed() 的差异、信号处理机制及实战用法。读完本文，你将掌握如何安全、可等待地关闭浏览器进程，并理解其底层如何通过「钩子 + 退出事件 Promise」保证一次性且不泄漏的清理。

1. close() 方法签名：一个可 await 的关闭约定

依据官方 API 文档，Process.close() 的定义非常简单：

class Process {
  close(): Promise<void>;
}

• 返回值：Promise<void>。调用方可以 await process.close()，从而获得一个明确的「浏览器进程已经结束」的时机点。
• 所属类：Process，它封装了 @puppeteer/browsers 通过 launch() 启动的浏览器子进程。
• 相关兄弟方法：同类的其他生命周期方法还包括同步的 kill()、同样返回 Promise<void> 的 hasClosed()、日志查询 getRecentLogs() 以及等待特定输出行的 waitForLineOutput()。

方法体虽只有三行文档，但其语义是整个 Process 类的核心：它提供的是**优雅关闭（graceful close）**而非单纯的强杀。

2. 源码视角：close() 内部到底做了什么

在仓库 packages/browsers/src/launch.ts 中，Process 类的 close() 实现位于 447-453 行：

async close(): Promise<void> {
  await this.#runHooks();
  if (!this.#exited) {
    this.kill();
  }
  return await this.#browserProcessExiting;
}

整个方法可以拆解为三个阶段：

2.1 先执行一次性退出钩子（onExit Hook）

#runHooks() 通过 #hooksRan 标志保证钩子只执行一次：

async #runHooks() {
  if (this.#hooksRan) {
    return;
  }
  this.#hooksRan = true;
  await this.#onExitHook();
}

这个设计源于源码注释所描述的场景：浏览器进程可能由驱动方（当前 Node 进程）主动关闭，也可能被外部终止，但无论被触发多少次，清理钩子都只应执行一次。钩子内容由 LaunchOptions 的 onExit 字段 注入，默认为空实现。

2.2 进程未退出时调用 kill() 强杀

若进程尚未退出（内部 #exited 标志为 false），close() 会转入 kill() 的实现。kill() 的底层逻辑值得注意：

• 先探测进程是否真的存在：通过 process.kill(pid, 0) 检查（pidExists），避免因可执行文件路径非法、进程从未成功启动而产生无谓报错。
• Windows 平台：优先执行 taskkill /pid <pid> /T /F，以便连同整个子进程树一起终止；若因权限等原因失败，再退回 Node 原生 child.kill()。
• 类 Unix 平台：利用启动时的 detached: true 特性（子进程成为新进程组组长），以负数进程组 ID 发送 process.kill(-pid, 'SIGKILL')，从而一次性清理整个进程组；失败时同样回退到原生 kill('SIGKILL')。

2.3 返回退出事件 Promise，等待真正结束

构造器（browsers.process.constructor）中会创建并保存一个 #browserProcessExiting Promise，并挂上子进程的 exit 事件监听：

this.#browserProcessExiting = new Promise((resolve, reject) => {
  this.#browserProcess.once('exit', async () => {
    this.#clearListeners();
    this.#exited = true;
    try {
      await this.#runHooks();
    } catch (err) {
      reject(err);
      return;
    }
    resolve();
  });
});

close() 最终 return await this.#browserProcessExiting，意味着：

• 该 Promise 只有在浏览器子进程真正触发 exit 事件、并且监听器清理（#clearListeners()，含进程信号监听与 AbortSignal 监听）完成后才会 resolve；
• 若退出钩子执行中抛错，该 Promise 会 reject，close() 的调用方能够捕获到清理阶段的异常。

换句话说，await process.close() 并不只是在「发出一个杀死命令」后立刻返回，而是保证进程已退出、监听已清理、钩子已执行完毕——这是进程管理中最容易遗漏的三个时间点。

3. close()、kill() 与 hasClosed() 三者的分工

为了准确使用它们，需要区分三个方法的不同语义：

方法	签名	核心语义	使用建议
close()	Promise<void>	运行退出钩子 → 必要时 kill → 等待退出事件 Promise	推荐的主路径：需要确定性清理时使用
kill()	void	仅发出强杀信号，立即返回，不等待、不保证钩子	事件回调（如收到 SIGINT）等不需要等待的兜底场景
hasClosed()	Promise<void>	直接返回同一个 #browserProcessExiting Promise，不触发任何关闭动作	只关心「是否已经关闭」，或对同一进程多次 await 结果

一个容易被忽略的实现细节：由于 close() 与 hasClosed() 共享同一个 #browserProcessExiting 实例，即使 close() 已经被调用过、浏览器已经退出，之后再次 await process.hasClosed() 或 await process.close() 依然会立即完成，不会抛错，也不会重复杀死进程——这是幂等性的体现，让多次调用变得安全。

4. 信号处理：驱动进程崩溃/中断时浏览器如何被回收

Process 之所以能避免「Node 进程退出后残留浏览器僵尸进程」，依赖于构造器中对宿主进程事件的订阅（launch.ts），其回调行为如下：

#onDriverProcessExit = (_code: number) => {
  this.kill();
};

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

• 宿主进程正常退出（exit）→ 立即 kill() 兜底回收子进程；
• 宿主收到 SIGINT（如终端 Ctrl+C）→ 强杀后以退出码 130 结束自身；
• 宿主收到 SIGTERM / SIGHUP → 走 close() 这条优雅关闭路径。

相应地，LaunchOptions 暴露了 handleSIGINT、handleSIGTERM、handleSIGHUP 三个布尔开关（默认均为 true），允许关闭这套自动回收机制；同时还可通过 signal?: AbortSignal 传入外部中止信号——一旦 abort，构造器注册的 #onAbort 会调用 kill()。以上共同构成了多通道、防泄漏的进程回收网络。

5. 实战用法：启动、等待就绪、优雅关闭

Process.close() 的标准使用场景，是从 @puppeteer/browsers 用 launch() 启动浏览器、等待其输出就绪标志（如 DevTools WebSocket 地址）之后执行收尾。仓库中的端到端测试 packages/browsers/test/src/chrome/launch.test.ts（firefox 与 chromium 亦有对应版本）给出了可参考的完整模式：

import {
  launch,
  CDP_WEBSOCKET_ENDPOINT_REGEX,
} from '@puppeteer/browsers';

// 1. 启动浏览器进程
const process = launch({
  executablePath: '/path/to/chrome', // 可用 computeExecutablePath / ChromeHeadlessShellSettings 获取
  args: ['--headless=new', '--no-sandbox'],
});

try {
  // 2. 等待浏览器在 stdout 上输出 DevTools WebSocket 端点
  const wsEndpoint = await process.waitForLineOutput(
    CDP_WEBSOCKET_ENDPOINT_REGEX,
  );
  console.log('DevTools endpoint:', wsEndpoint);

  // 3. ...使用该端点连接、驱动浏览器...

  // 4. 收尾：优雅关闭并等待进程真正结束
  await process.close();
  console.log('Browser process closed.');
} finally {
  // 兜底：即使业务抛错，也要确保子进程不残留
  if (!process.hasClosed()) {
    process.kill();
  }
}

说明与注意事项：

• waitForLineOutput(regex, timeout) 会一边缓冲浏览器 stdout/stderr（内部默认保留最近 1000 行日志，可通过 getRecentLogs() 读取），一边匹配正则，匹配到即 resolve 出捕获组；进程提前退出或超时会 reject 并附带完整 stderr 日志与排障指引。
• 仓库测试的断言也印证了 close() 与日志的联动：例如 chrome 的 launch 测试中，先 await process.waitForLineOutput(...) 拿到 ws://127.0.0.1:9222/devtools/browser/... 格式的端点，随后 await process.close()，再用 process.getRecentLogs() 校验日志内容非空。
• 在需要「进程必须被回收、但不关心是否已退出」的回调上下文（如 signal handler）使用 kill()；在需要确定性收尾的业务主流程使用 await close()；两方法互补而非替代。

6. 小结：何时选择 close()，以及它的边界

Process.close() 是 @puppeteer/browsers 推荐的浏览器进程收尾入口，其价值可归纳为三点：

1. 确定性：返回的 Promise 在进程退出、监听清理、钩子执行完毕后才完成，便于外层精确编排后续步骤；
2. 幂等性：通过 #exited 与 #hooksRan 标志，重复调用不会重复杀进程、不会重复执行钩子；
3. 纵深防御：kill 失败时仍会抛出带明确解释的错误信息（Puppeteer was unable to kill the process...），引导用户检查残留进程。

使用边界也需了解：close() 最终依赖 SIGKILL 级别的强杀来回收进程（实现位于 launch.ts），因此它不承诺「让浏览器像用户手动关闭一样做落盘、同步等收尾」，它保证的是宿主机侧进程树的确定性回收与资源释放。若你的场景还需要在关闭前与浏览器内部逻辑交互（例如触发 flush、保存状态），应当通过 CDP/WebDriver BiDi 连接在调用 close() 之前完成，而不是寄希望于 close() 本身。