Puppeteer ConnectionTransport.close() 方法解析：浏览器协议连接的生命周期收尾

ConnectionTransport.close() 是 Puppeteer 与浏览器之间底层通信链路上最小的一个接口方法，签名只有 close(): void，但它承担着一个关键职责：在连接生命周期结束时，主动关闭与浏览器的底层传输通道（WebSocket 或管道）。读懂它，你能理解 Puppeteer 中 browser.disconnect()、进程退出清理等操作的真实落点，也能明白为什么协议连接的关闭是"命令式发起、回调式确认"的异步两段过程。本文基于 ConnectionTransport.close() API 文档 及其接口定义，结合 puppeteer-core 的源码实现逐一展开。

接口定义：一个极简的传输抽象

ConnectionTransport 定义在 ConnectionTransport.ts 中，完整签名如下：

/**
 * @public
 */
export interface ConnectionTransport {
  send(message: string): void;
  close(): void;
  onmessage?: (message: string) => void;
  onclose?: () => void;
}

从源码结构看，这是一个典型的"窄接口"设计：

成员	类型	职责
send(message)	(message: string) => void	向浏览器发送一条 JSON 序列化的协议消息（CDP 或 WebDriver BiDi）
close()	() => void	关闭底层传输，是本文主题
onmessage	optional (message: string) => void	浏览器返回消息时触发
onclose	optional () => void	传输关闭时触发

close() 有两个值得注意的设计特征：

1. 返回 void，不返回 Promise。它只是一个"关闭请求"，不会等待对端（浏览器）确认连接已经断开。真正的关闭确认走的是另一条路——onclose 回调（对应 ConnectionTransport.send() 文档 中同一接口的对称方法）。
2. 与 onclose 构成"请求—事件"闭环。调用方发起 close()，传输层在底层 Socket 真正断开后触发 onclose，上层 Connection 收到该事件后才把自身标记为已关闭并做资源清理。这个模式在 CDP 和 BiDi 两条连接栈中完全一致。

四种内置传输的 close() 实现

仓库中 ConnectionTransport 有四个实现类，close() 都是对底层对象的薄封装，但底层对象各不相同：

NodeWebSocketTransport（Node 环境，最常用）

NodeWebSocketTransport.ts 基于 ws 库，close() 实现为一行：

close(): void {
  this.#ws.close();
}

构造时它还会注册底层事件转发，形成完整的闭环：

this.#ws.addEventListener('close', () => {
  if (this.onclose) {
    this.onclose.call(null);
  }
});

值得留意的连接参数（同文件的 create 静态方法）：maxPayload: 256 * 1024 * 1024（单条消息上限 256MB，保证大体积的协议响应不被截断）、perMessageDeflate: false（关闭压缩以换吞吐）、并附带 User-Agent: Puppeteer <version> 请求头。此外该实现会"静默记录所有 error 事件"，源码注释写得很直白——Silently log all errors - we don't know what to do with them，即 WebSocket 的错误不会直接抛出，只写入 DEBUG_PREFIXES.error 日志，避免未处理的 socket 异常打断上层逻辑。

PipeTransport（launch 管道模式）

通过 puppeteer.launch() 启动浏览器时，Puppeteer 与浏览器进程之间走的是标准输入/输出管道，由 PipeTransport.ts 封装。它的 close() 关闭的是进程 stdout/stdin 而非 Socket，语义同样是"发起关闭"，断开后由底层流事件触发 onclose。

BrowserWebSocketTransport（浏览器端运行 Puppeteer）

当 Puppeteer 在浏览器（或 Service Worker、扩展后台）中运行时，没有 Node 的 ws 库，改用 BrowserWebSocketTransport.ts 封装原生 WebSocket 全局对象。其 close() 同样委托给 ws.close()，消息/关闭/错误事件的注册方式与 Node 版本对称，体现了同一接口在两个运行时的等价性。

ExtensionTransport（Chrome 扩展环境）

ExtensionTransport.ts 服务于 Chrome 扩展这一特殊宿主，其 close() 的调用同样出现在测试 ExtensionTransport.test.ts（约 L90）的 afterEach 清理中。

四个实现的共性：close() 全部是同步的"尽力而为"式关闭，没有任何返回值；确认关闭必须依赖 onclose。

上层调用链：谁在调用 transport.close()？

CDP 栈：Connection.dispose()

close() 在生产代码中的调用点在 cdp/Connection.ts。Connection 是 CDP 协议连接的主类，其构造函数（L71-L73）先完成回调绑定：

this.#transport = transport;
this.#transport.onmessage = this.onMessage.bind(this);
this.#transport.onclose = this.#onClose.bind(this);

随后 dispose()（L285-L288）把两步拆得很清楚：

dispose(): void {
  this.#onClose();      // 先做本地上线清理
  this.#transport.close();  // 再关闭底层传输
}

顺序上是"先清理自己、再断开连接"。#onClose()（L270-L283）执行了四件事：

1. 幂等保护：若 #closed 已为 true 直接返回；
2. 将 transport.onmessage / transport.onclose 置为 undefined，切断后续事件回传（防止关闭过程中收到残余消息再次触发处理）；
3. #callbacks.clear() 清空所有等待中的命令回调；
4. 遍历所有 CdpCDPSession 调用 onClosed()，清空会话表，最后发出 CDPSessionEvent.Disconnected 事件。

这里还有一个与 close() 相关的防御性设计：_rawSend()（L166-L168）在发送前检查 #closed，若连接已关闭则立即 reject 一个 ConnectionClosedError('Connection closed.')（定义于 Errors.ts）。也就是说，"关闭"不只是断开 Socket，更是让所有后续协议命令快速失败，而不是在已死的通道上排队等待超时。

BiDi 栈：对称的实现

WebDriver BiDi 栈的 bidi/Connection.ts 采用几乎相同的双段结构（L197-L215）：

unbind(): void {
  if (this.#closed) {
    return;
  }
  this.#closed = true;
  // Both may still be invoked and produce errors
  this.#transport.onmessage = () => {};
  this.#transport.onclose = () => {};
  this.#callbacks.clear();
}

dispose(): void {
  this.unbind();
  this.#transport.close();
}

细节差异颇有意味：BiDi 的 unbind() 不直接把回调置空，而是替换成空函数，注释说明原因是"这两个回调仍可能被调用并产生错误"——即底层 WebSocket 可能在 dispose() 之后仍异步触发 close 事件，空函数能保证不会误触已清理的连接逻辑。CDP 栈则直接置 undefined。从源码结构看，两者是同一安全目标（关闭后不再响应底层事件）在不同栈中的两种落地方式。

关闭的确认：onclose 才是"已关闭"

再次强调 close() 的语义边界：它是单向命令，不携带完成信号。整个确认链是：

connection.dispose()
  → transport.close()          // 同步发起，立即返回
  → （底层 ws / pipe 真正断开）
  → transport 触发 onclose     // 异步事件
  → Connection.#onClose()      // 置 #closed、清回调、清会话、发 Disconnected

因此代码中判断"连接是否真的断了"，应依赖 Connection._closed 状态或 Disconnected 事件，而不能假设 close() 调用返回后连接已断。若浏览器侧（如进程崩溃）先断开，方向则反过来：底层先触发 onclose，#onClose() 自行完成清理——这也是为什么 #onClose() 内有 #closed 幂等检查：本端发起关闭与远端先行断开两条路径可能先后各走一次。

测试中的验证方式

仓库测试把 close() 当作标准的资源清理动作使用，可直接作为用法范本：

• PipeTransport.test.ts（L56-L58）：afterEach 中调用 transport.close() 释放管道资源，同时该测试还验证了 onmessage 按序分发且每条消息先让出微任务队列；
• NodeWebSocketTransport.test.ts（L34）：同样在 afterEach 中 transport.close() 关闭真实的 WebSocket 连接；
• ExtensionTransport.test.ts（约 L90）：扩展传输的关闭清理。

这种"beforeEach 建传输、afterEach 调 close()"的模式，也印证了接口的设计意图：close() 是给资源管理（测试清理、browser.disconnect()、进程退出）使用的确定性关闭动作，幂等性由上层连接类保证。

小结

• ConnectionTransport.close(): void 是关闭底层传输（WebSocket/管道）的同步命令，不提供完成确认，完成确认由 onclose 事件回调承载（接口定义见 ConnectionTransport.md）。
• 四个内置实现（NodeWebSocketTransport、BrowserWebSocketTransport、PipeTransport、ExtensionTransport）的 close() 均为一行委托，差异只在底层载体。
• 生产代码中它在 CDP 栈由 Connection.dispose() 调用，在 BiDi 栈由 bidi Connection.dispose() 调用，且都遵循"先 #onClose/unbind 清理本地上线，后 transport.close() 断开"的固定顺序；连接已关闭后，_rawSend 会以 ConnectionClosedError 快速拒绝后续命令。
• 自定义传输（如需接入非 WebSocket 的协议通道）只需实现 send、close 两个方法及可选的 onmessage/onclose 回调，即可接入 Puppeteer 的连接栈。