Puppeteer Browser.close() 深入解析：如何彻底关闭浏览器进程与所有页面

在 Puppeteer 中，Browser.close() 是浏览器实例生命周期的终结点：它负责关闭这个浏览器及其关联的全部 Page 对象。对于长时间运行、批量启动浏览器的自动化脚本与测试框架来说，理解 close() 的确切语义——它与 disconnect() 的区别、底层如何终止进程、协议层面如何清理连接——是避免僵尸进程和资源泄漏的关键。本文以官方 API 文档 puppeteer.browser.close.md 为主体，结合 puppeteer-core 中 CDP 与 WebDriver BiDi 两套实现，完整剖析 close() 的签名、行为差异与底层调用链。

一、API 定义：签名与返回

官方文档 puppeteer.browser.close.md 对 Browser.close() 的定义如下：

Closes this browser and all associated pages.

（关闭这个浏览器及其所有关联页面。）

方法签名为：

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

Returns: Promise<void>

三个要点值得注意：

1. close() 是抽象方法。它声明在抽象基类 Browser 上，没有基类实现，具体行为由协议实现类（CDP 版或 BiDi 版）分别提供。
2. 返回的是 Promise。必须 await，否则脚本可能先于关闭流程结束就退出，导致清理动作未完整执行。
3. 作用范围是整个浏览器：不只是断开连接，而是连同浏览器进程（若是 launch() 创建的）一起终结，所有 Page、Worker、Target 随之失效。

在抽象类源码中，close() 与 disconnect() 是相邻声明的一对方法，注释本身就点明了两者的分工（packages/puppeteer-core/src/api/Browser.ts）：

/**
 * Closes this {@link Browser | browser} and all associated
 * {@link Page | pages}.
 */
abstract close(): Promise<void>;

/**
 * Disconnects Puppeteer from this {@link Browser | browser}, but leaves the
 * process running.
 */
abstract disconnect(): Promise<void>;

二、典型用法：官方示例中的 close()

Browser 类文档 给出的两个标准示例都以 close() 收尾，这也是最常用的两种场景。

场景 1：launch 后完整关闭

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close(); // 关闭浏览器进程及所有页面

这里 puppeteer.launch() 由 Puppeteer 自己拉起了浏览器子进程（browser.process() 可拿到对应的 ChildProcess），因此 close() 会连同该进程一起清理。

场景 2：断开后重连，最后再彻底关闭

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
// Store the endpoint to be able to reconnect to the browser.
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from the browser.
await browser.disconnect(); // 仅断开连接，浏览器进程继续运行

// Use the endpoint to reestablish a connection
const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close the browser.
await browser2.close(); // 通过新连接彻底关闭浏览器

这个例子清晰地演示了 disconnect() 与 close() 的本质区别：disconnect() 之后浏览器仍然活着，可以通过 wsEndpoint() 重新 connect() 回来；而 close() 执行后浏览器进程终止，无法再重连。

三、close() 与 disconnect() 的行为对照

维度	close()	disconnect()
浏览器进程	终止（launch 场景）	继续运行
协议连接	销毁	销毁
能否重连	不能	能（通过 wsEndpoint()）
返回类型	Promise<void>	Promise<void>
典型用途	脚本/测试结束时的完整清理	移交控制、长驻服务中临时释放句柄

文档 puppeteer.browser.disconnect.md 对后者的描述是 “Disconnects Puppeteer from this browser, but leaves the process running.”，与 close() 形成互补。

四、源码深潜：两套协议实现中的 close()

Puppeteer 同时支持 Chrome DevTools Protocol（CDP）和 WebDriver BiDi 两套协议，close() 在这两个实现分支中的清理逻辑各有特点。

4.1 CDP 实现：closeCallback + disconnect

CDP 版 Browser 的 close() 实现非常短：

override async close(): Promise<void> {
  await this.#closeCallback.call(null);
  await this.disconnect();
}

override disconnect(): Promise<void> {
  this.#targetManager.dispose();
  this.#connection.dispose();
  this._detach();
  return Promise.resolve();
}

调用链分两步：

1. #closeCallback：一个在构造时注入的回调（类型定义为 BrowserCloseCallback，见 packages/puppeteer-core/src/api/Browser.ts#L60-L63，即 () => Promise<void> | void）。它由外部启动/连接流程构造，负责向浏览器下发“真正关闭”的指令或终止进程；CDP 浏览器构造时若未提供则退化为空函数（this.#closeCallback = closeCallback || (() => {})，L165）。
2. disconnect()：无论进程是否已退出，都统一销毁 target 管理器与协议连接，使该 Browser 实例彻底不可用。

这种“回调 + 断连”的结构解释了为什么文档强调 close() 会关闭“所有关联页面”——连接销毁后，挂在连接上的所有会话（session）自然全部失效。

4.2 closeCallback 从哪里来

从源码结构看，closeCallback 在两条路径上被构造：

• launch 路径：浏览器由 Puppeteer 拉起时，BrowserLauncher.ts 中的 createBiDiOverCdpBrowser / createBiDiBrowser 等方法接收 closeCallback: BrowserCloseCallback 参数并透传给 BidiBrowser.create，由拉起方注入进程清理逻辑；
• connect 路径：BrowserConnector.ts 根据目标端点实际支持的协议生成不同的回调——纯 BiDi 端点发送 browser.close 命令，BiDi over CDP 端点则回退发送 CDP 的 Browser.close 命令，且都包在 catch 中静默记录错误而不向外抛出：

closeCallback: async () => {
  // In case of BiDi over CDP, we need to close browser via CDP.
  await cdpConnection.send('Browser.close').catch(error => {
    logger?.(DEBUG_PREFIXES.error)?.(error);
  });
},

这个设计保证了 close() 的幂等性倾向：即使浏览器已经自行退出、下发关闭命令失败，回调也只是记一条 debug 错误日志，不会让 close() 的 Promise 以异常拒绝。

4.3 BiDi 实现：幂等、静默失败与连接释放

BiDi 版 Browser 的 close() 增加了一层防御：

override async close(): Promise<void> {
  if (this.connection.closed) {
    return; // 连接已关闭则直接返回（幂等）
  }

  try {
    await this.#browserCore.close();      // 发送协议级 browser.close
    await this.#closeCallback?.call(null); // 再执行启动方注入的清理
  } catch (error) {
    // Fail silently.
    this.#logger?.(DEBUG_PREFIXES.error)?.(error);
  } finally {
    this.connection.dispose(); // 无论如何都释放连接
  }
}

其中 this.#browserCore.close() 最终在 bidi/core/Browser.ts 中向浏览器会话发送标准的 browser.close 命令，随后标记浏览器为 disposed 状态：

async close(): Promise<void> {
  try {
    await this.session.send('browser.close', {});
  } finally {
    this.dispose('Browser already closed.', true);
  }
}

从这段实现可以读出三个工程细节，它们对使用者都是可验证的事实：

• 幂等保护：连接已关闭时重复调用 close() 会直接 return，不会产生副作用；
• 静默失败（fail silently）：关闭过程中的异常只写入 DEBUG_PREFIXES.error 日志流，不向调用方抛出——这与文档承诺的“关闭浏览器并所有页面”的语义一致，调用方只需 await browser.close() 即可；
• finally 释放连接：即使协议命令失败，本地连接对象也一定被 dispose()，避免句柄泄漏。

4.4 与资源释放协议（dispose symbol）的关系

Browser 基类还实现了 TypeScript 5.2 的显式资源管理协议（packages/puppeteer-core/src/api/Browser.ts#L858-L871），这是理解 close() 语义的另一条线索：

override [disposeSymbol](): void {
  return void this[asyncDisposeSymbol]().catch(error => {
    this.#logger?.(DEBUG_PREFIXES.error)?.(error);
  });
}

override async [asyncDisposeSymbol](): Promise<void> {
  if (this.process()) {
    await this.close();       // 有子进程 → 彻底关闭
  } else {
    await this.disconnect(); // 无子进程（connect 得到）→ 仅断开
  }
  await super[asyncDisposeSymbol]();
}

也就是说：用 puppeteer.launch() 得到的浏览器（process() 非空）在异步释放时会走 close()；而用 puppeteer.connect() 得到的浏览器（process() 为 null，见 api/Browser.ts#L500-L503 的注释）在释放时只走 disconnect()，因为 Puppeteer 不认为自己“拥有”那个外部进程。这为“何时该 close、何时该 disconnect”提供了一个清晰的判定标准：进程归属权决定释放方式。

五、实践要点

结合上述实现，使用 Browser.close() 时建议遵循以下模式：

1. 始终 await browser.close()。close() 返回 Promise，CDP 实现中它需要依次完成回调与断连，未等待就退出的脚本可能留下未清理的中间状态。
2. 用 connected 属性判断实例可用性。Browser.connected（docs/api/puppeteer.browser.md 中的只读属性，CDP 实现见 cdp/Browser.ts#L709-L711）在 close()/disconnect() 之后变为 false，对 close() 之后的调用应视为无意义。
3. close 与 disconnect 不要混用收尾：对 launch() 创建的浏览器用 close() 才能终止进程，仅 disconnect() 会造成浏览器进程常驻；对 connect() 接入的外部浏览器，若不想杀掉对方进程，应使用 disconnect()。
4. 测试代码是标准参照。仓库测试中大量用例在 teardown 阶段调用 browser.close()，例如 test/src/launcher.test.ts 与测试工具 test/src/mocha-utils.ts，可作为浏览器生命周期管理的项目内范例。

六、小结

Browser.close() 虽然只有一行文档描述和 Promise<void> 的签名，但它是 Puppeteer 浏览器生命周期管理的收口点：CDP 实现通过注入的 closeCallback 加连接销毁完成清理（cdp/Browser.ts#L690-L700），BiDi 实现则在发送 browser.close 协议命令的基础上叠加了幂等判断、静默失败与连接强制释放（bidi/Browser.ts#L258-L272）。理解了 close() 与 disconnect() 的进程归属语义，以及基类 dispose 协议中“有进程则 close、无进程则 disconnect”的分流逻辑（api/Browser.ts#L858-L871），就能在自动化脚本、测试框架与常驻服务中正确地完成浏览器资源回收。