Puppeteer Browser.disconnect() 深度解析：断开控制连接而不终止浏览器进程

本文基于 Puppeteer 官方 API 文档 Browser.disconnect()，围绕「断开 Puppeteer 与浏览器之间的控制连接、但让浏览器进程继续存活」这一核心能力展开：先完整给出方法签名与返回值约定，再结合 puppeteer-core 源码 剖析 CDP 与 WebDriver BiDi 两条协议路径下的 disconnect 实现，最后给出断开重连（disconnect / reconnect）的可运行工作流与测试用例佐证。读完后，你将掌握在多连接、长驻浏览器、资源治理等场景下正确使用 disconnect() 的完整方案，以及它与 close() 的本质区别。

方法签名与返回值

Browser.disconnect() 是 Browser 抽象类 上声明的抽象方法，官方文档给出的行为定义只有一句话，但信息量很足：

Disconnects Puppeteer from this browser, but leaves the process running. （将 Puppeteer 与本浏览器断开连接，但让进程继续运行。）

抽象签名如下（与 docs/api/puppeteer.browser.disconnect.md 中的 Signature 一致）：

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

Returns: Promise<void>

该声明位于 packages/puppeteer-core/src/api/Browser.ts，注意它是 abstract 方法——Browser 类自身不实现任何断开逻辑，具体的断开行为由各协议实现（CDP、BiDi）分别覆写。Promise<void> 的返回值意味着方法可等待、可挂进 await 链，但断开本身不产生业务数据。

语义核心：disconnect() 与 close() 的区别

理解 disconnect() 的关键是分清「断开连接」与「关闭浏览器」这两件事：

方法	浏览器进程	已打开的页面/标签页	已加载的页面状态（登录态、本地变量等）
browser.close()	终止（若由 launch() 启动）	全部销毁	丢失
browser.disconnect()	继续运行	保持打开	完整保留

源码中这一区分体现得非常直接。CDP 实现里 close() 是先执行关闭回调再断开连接：

override async close(): Promise<void> {
  await this.#closeCallback.call(null); // 真正关闭浏览器进程
  await this.disconnect();
}

而 disconnect() 只做「解除控制」，不触碰进程。此外，Puppeteer 还内置了一条生命周期兜底规则：当 Browser 实例被 using 语句管理并触发 asyncDisposeSymbol 时，若该实例拥有自己启动的进程则执行 close()，否则执行 disconnect()：

override async [asyncDisposeSymbol](): Promise<void> {
  if (this.process()) {
    await this.close();      // launch() 启动的：关进程
  } else {
    await this.disconnect(); // connect() 连接的：只断连
  }
  await super[asyncDisposeSymbol]();
}

也就是说：对 puppeteer.launch() 启动的浏览器，进程归它管，释放资源要 close()；对 puppeteer.connect() 连上的外部浏览器，进程不归它管，释放资源只需 disconnect()。这条规则也是判断你该用哪个方法的实用依据。

断开后重连：disconnect + connect 的标准工作流

断开连接的价值在于：浏览器进程可以长驻，而 Puppeteer 的控制权可以被多个客户端（或同一客户端的不同时刻）轮流接管。官方文档 Browser 类示例 2 给出的完整流程是「断开—重连」闭环：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
// 保存端点，以便重新连接浏览器。
const browserWSEndpoint = browser.wsEndpoint();
// 将 Puppeteer 与浏览器断开。
await browser.disconnect();

// 使用该端点重新建立连接
const browser2 = await puppeteer.connect({browserWSEndpoint});
// 关闭浏览器。
await browser2.close();

要点拆解：

1. 先取 wsEndpoint()，再 disconnect()。wsEndpoint() 返回形如 ws://HOST:PORT/devtools/browser/<id> 的 WebSocket URL（见 Browser.wsEndpoint() 文档）。disconnect() 之后旧的 Browser 对象即失效，重连必须依赖这个事先保存的端点字符串；
2. 用 puppeteer.connect({browserWSEndpoint}) 重新接管，参数约定见 Puppeteer.connect() 文档。注意 browserWSEndpoint、browserURL、transport、channel 四者只能传其一，否则抛出 "Exactly one of browserWSEndpoint, browserURL, transport or channel must be passed to puppeteer.connect" 错误（该断言可在 test/src/connect.test.ts 中看到）；
3. 重连后拿到的是一个全新的 Browser 对象，它会重新发现浏览器中已存在的 target 与页面，页面内的登录态、window 变量等运行时状态原样保留——这正是「进程继续运行」带来的收益；
4. 重连对象负责收尾时才调用 close()。

同样的「连—做—断」模式在仓库测试中也反复出现，例如 test/src/connect.test.ts 用 browserURL 连接、newPage() 后 evaluate 验证、再 await browser1.disconnect() 收尾；test/src/launcher.test.ts 中则大量使用 remote.disconnect() / browser.disconnect() 释放外部连接的浏览器实例。

源码实现剖析：CDP 路径下 disconnect 做了什么

CDP 协议下的实现位于 packages/puppeteer-core/src/cdp/Browser.ts，整个方法只有三步：

override disconnect(): Promise<void> {
  this.#targetManager.dispose();   // 1. 停止 target 跟踪
  this.#connection.dispose();      // 2. 关闭与浏览器的协议连接
  this._detach();                  // 3. 解除事件订阅
  return Promise.resolve();
}

从源码结构看，这三步分别对应：

• #targetManager.dispose()：TargetManager 负责监听浏览器的 target 增删改事件（见 _attach() 中的订阅），dispose 后 Puppeteer 不再感知页面/iframe 的创建与销毁；
• #connection.dispose()：关闭底层 CDP 连接（WebSocket 或 pipe）。Connection 一旦关闭，所有未完成的协议调用会被清理，connected 属性随即翻转——其实现就是一行 return !this.#connection._closed;；
• _detach()：调用 #subscriptions.dispose()，一次性释放所有事件订阅（连接断开事件、target 事件等），防止监听器泄漏。

值得注意的细节：CDP 版 disconnect() 是同步完成的——它直接返回 Promise.resolve()，因为断开本地连接不需要与浏览器协商。且它不调用 #closeCallback，因此浏览器进程完全不受影响。

BiDi 路径：优雅协商式断开

WebDriver BiDi 协议下的实现位于 packages/puppeteer-core/src/bidi/Browser.ts，与 CDP 的「直接切断」不同，BiDi 版会先尝试一次正式的会话结束协商：

override async disconnect(): Promise<void> {
  try {
    await this.#browserCore.session.end(); // 发送 session.end 请求
  } catch (error) {
    // Fail silently. 静默失败
    this.#logger?.(DEBUG_PREFIXES.error)?.(error);
  } finally {
    this.connection.dispose();           // 无论如何都释放连接
  }
}

从源码结构看，这里采用 try/catch/finally 的设计意图是：session.end() 可能因连接已处于异常状态而失败，但释放 connection 必须无条件执行，错误仅记入调试日志（"Fail silently"）。这提示使用者：disconnect() 在 BiDi 路径下是真正 async 的（涉及一次网络往返），且它保证尽力而为地清理资源而不向调用方抛错。

与 connected 属性和 disconnected 事件的联动

disconnect() 之后，实例上的两个可观测状态会发生变化，方便你在代码中感知断开：

1. browser.connected 属性（readonly boolean，文档见 Browser 属性表）：CDP 实现中该属性直接反映底层连接是否关闭，调用 disconnect() 后立刻变为 false；
2. BrowserEvent.Disconnected 事件：抽象类中的事件定义 说明其触发条件包括「浏览器进程终止」与「调用了 Browser.disconnect()」两种情形。监听该事件是捕获「控制权丢失」的统一方式，例如：

browser.on(puppeteer.BrowserEvent.Disconnected, () => {
  console.log('与浏览器的连接已断开（可能是 disconnect() 或浏览器进程退出）');
});

实用建议与常见误区

• 断开前务必先保存 wsEndpoint()。一旦 disconnect()，旧对象无法恢复，端点是重连的唯一凭据（除非你通过 --remote-debugging-port 暴露了调试端口，可用 browserURL 走 http://HOST:PORT/json/version 重新发现端点）；
• 不要用 disconnect() 来「省资源地关闭浏览器」。对 launch() 启动的浏览器，进程仍会在后台运行并占用内存；需要终结进程时应使用 close()；反过来，对 connect() 接入的外部浏览器，调用 close() 会关闭整个浏览器，通常不是你想要的；
• using 关键字会自动选对方法。using browser = await puppeteer.connect(...) 在作用域结束时自动执行 disconnect()（因为 process() 返回 null），这是当前版本推荐的资源治理写法，其实现依据即前文 api/Browser.ts 的 asyncDisposeSymbol；
• 断开不等于撤销副作用。断开前已通过协议设置的下载行为、权限覆盖、请求拦截等配置仍存在于浏览器进程中，重连后依然生效。

小结

Browser.disconnect() 虽然只是一句「断开连接但保留进程」的抽象声明（docs/api/puppeteer.browser.disconnect.md），但支撑它的是清晰的三层结构：抽象层在 api/Browser.ts 定义签名并绑定 using 资源语义；CDP 层（cdp/Browser.ts）以 dispose targetManager + dispose connection + detach 订阅三步同步完成解绑；BiDi 层（bidi/Browser.ts）则先协商 session.end 再强制释放连接。掌握它与 close() 的边界、配合 wsEndpoint() 与 puppeteer.connect() 完成重连闭环，就覆盖了多客户端接管、长驻浏览器复用这两类 Puppeteer 进阶场景的核心诉求。