Puppeteer BrowserContext.close() 详解：关闭浏览器上下文与隔离环境的 API 及源码实现

本文聚焦 Puppeteer 官方 API 文档中的 BrowserContext.close() 方法，完整讲解其签名、返回值与使用限制，并结合仓库源码剖析 CDP 与 WebDriver BiDi 两种协议下关闭上下文的具体实现路径。读完本文，你将掌握如何安全地创建、使用和销毁隔离浏览器上下文（incognito 风格环境），理解"默认上下文不可关闭"这一约束的底层机制，并学会利用 using 语句自动释放上下文资源。

方法签名与行为定义

BrowserContext.close() 是 BrowserContext 抽象类上的实例方法，用于关闭指定的浏览器上下文以及该上下文内关联的所有 Page。官方文档给出的签名如下：

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

关键属性一览：

项目	说明
方法修饰符	abstract（抽象方法，由各协议实现类覆写）
参数	无
返回值	Promise<void>，resolve 后表示上下文已关闭
核心行为	关闭该上下文及其内所有页面
使用限制	默认浏览器上下文（default browser context）不能被关闭

在抽象基类 BrowserContext 源码中可以看到该方法的完整 JSDoc 声明：

/**
 * Closes this {@link BrowserContext | browser context} and all associated
 * {@link Page | pages}.
 *
 * @remarks The
 * {@link Browser.defaultBrowserContext | default browser context} cannot be
 * closed.
 */
abstract close(): Promise<void>;

BrowserContext 代表浏览器内一个个独立的"用户上下文"：每个上下文拥有相互隔离的存储（Cookie、localStorage 等）。在 Chrome 中，所有非默认上下文都是 incognito（无痕）模式，适合做多账号隔离、一次性任务等场景。因此 close() 承担着"销毁一整批页面 + 释放整个隔离存储"的资源回收职责。

基本用法：创建、使用到关闭

完整的上下文生命周期是"创建 → 建页操作 → 关闭"。BrowserContext 类文档给出的标准示例如下：

// 创建一个新的浏览器上下文
const context = await browser.createBrowserContext();
// 在上下文内创建新页面
const page = await context.newPage();
// ... 对页面做一些操作 ...
await page.goto('https://example.com');
// 上下文不再需要时销毁它
await context.close();

几个使用要点：

• 上下文通过 Browser.createBrowserContext() 创建，该选项还接受 proxyServer、proxyBypassList、downloadBehavior 等参数（在 CDP 实现中对应 Target.createBrowserContext 命令）。
• 关闭上下文会连带关闭其中全部页面，无需逐个调用 page.close()；测试用例"should close all belonging targets once closing context"（browsercontext.test.ts）验证了这一点：关闭上下文后 browser.pages() 数量从 2 恢复到 1。
• 关闭后，该上下文会从 browser.browserContexts() 列表中移除，可以通过这一变化确认关闭是否生效。

默认浏览器上下文不可关闭

文档明确标注：默认浏览器上下文不能被 close() 关闭。这不是文档层面的口头约定，而是两种协议实现中都会抛错的硬约束：

• CDP 实现（cdp/BrowserContext.ts）：

override async close(): Promise<void> {
  assert(this.#id, 'Default BrowserContext cannot be closed!');
  await this.#browser._disposeContext(this.#id);
}

• WebDriver BiDi 实现（bidi/BrowserContext.ts）：

override async close(): Promise<void> {
  assert(
    this.userContext.id !== UserContext.DEFAULT,
    'Default BrowserContext cannot be closed!',
  );
  // ...
}

两者都在执行关闭动作前通过 assert 检查是否为默认上下文，若是则抛出 message 含 "cannot be closed" 的错误。仓库测试"should not be able to close default context"（browsercontext.test.ts）正是断言了这一点：

const defaultContext = browser.defaultBrowserContext();
const error = await defaultContext!.close().catch(error => {
  return error;
});
expect(error).toBeInstanceOf(Error);
expect(error.message).toContain('cannot be closed');

从源码结构看，这个限制是合理的：默认上下文在浏览器启动时就存在，且可能承载浏览器级状态；若要彻底清理默认上下文内的内容，正确做法是关闭整个浏览器（browser.close()），而不是关闭上下文本身。

源码纵深：close() 在不同协议下的执行路径

Puppeteer 同时支持 CDP（Chrome DevTools Protocol）和 WebDriver BiDi 两套协议，close() 作为抽象方法在两边各有一份实现，底层机制不同但对外行为一致。

CDP 路径：Target.disposeBrowserContext

CDP 实现中，close() 委托给浏览器对象的 _disposeContext 方法（cdp/Browser.ts）：

async _disposeContext(contextId?: string): Promise<void> {
  if (!contextId) {
    return;
  }
  await this.#connection.send('Target.disposeBrowserContext', {
    browserContextId: contextId,
  });
  this.#contexts.delete(contextId);
}

调用链可以概括为：context.close() → browser._disposeContext(contextId) → 向浏览器发送 Target.disposeBrowserContext 命令 → 从内存中的 #contexts Map 删除该上下文。由于默认上下文的 #id 为 undefined，第一道防线就在这里：既没有 Target.disposeBrowserContext 命令可发，close() 入口处的 assert 也会先行拦截。

与之对应，创建侧的 createBrowserContext（cdp/Browser.ts）发送 Target.createBrowserContext 拿到 browserContextId 后，同样将其存入 #contexts Map——创建与销毁在数据结构上是严格对称的。

BiDi 路径：userContext.remove()

WebDriver BiDi 实现（bidi/BrowserContext.ts）的处理略有不同：

override async close(): Promise<void> {
  assert(
    this.userContext.id !== UserContext.DEFAULT,
    'Default BrowserContext cannot be closed!',
  );

  try {
    await this.userContext.remove();
  } catch (error) {
    this.#logger?.(DEBUG_PREFIXES.error)?.(error);
  }

  this.#targets.clear();
}

从源码结构看，BiDi 版本对 remove() 的失败做了容错（仅记录 debug 日志而不向上抛错），并显式清空本地 #targets 集合；相比之下 CDP 版本直接依赖协议命令的 Promise 结果。两者都体现了同一设计意图：关闭动作完成后，本地维护的 target 状态必须被清理，避免悬空引用。

closed 属性：如何判断上下文已被关闭

BrowserContext 还提供 closed 只读属性（boolean 类型），用于判断上下文当前是否已关闭。其实现非常简洁（api/BrowserContext.ts）：

/**
 * Whether this {@link BrowserContext | browser context} is closed.
 */
get closed(): boolean {
  return !this.browser().browserContexts().includes(this);
}

即：只要浏览器当前上下文列表中不包含自己，就认为已关闭。由于 close() 会把上下文从 browserContexts() 中移除（CDP 实现里是 #contexts.delete），该判断与关闭动作天然一致。

与 using 语句配合：自动关闭上下文

BrowserContext 基类 还实现了标准 Disposable 符号，将资源释放收敛到 close()：

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

override async [asyncDisposeSymbol](): Promise<void> {
  await this.close();
  await super[asyncDisposeSymbol]();
}

这意味着在支持 await using 的现代 JavaScript/TypeScript 环境中，可以这样写，作用域结束时自动触发 close()：

await using context = await browser.createBrowserContext();
const page = await context.newPage();
await page.goto('https://example.com');
// 离开作用域时上下文自动关闭（等价于 await context.close()）

这为批量创建一次性上下文的脚本（如并发抓取多个匿名会话）提供了防泄漏保障。

相关 API 对比：上下文、浏览器、页面三级关闭

Puppeteer 中 close() 存在于三个层级，职责边界清晰，实践中容易混淆：

方法	文档	作用范围	备注
BrowserContext.close()	链接	单个上下文及其内所有页面	默认上下文不可关闭
Browser.close()	链接	整个浏览器及关联页面	抽象声明见 api/Browser.ts；CDP 实现还会执行 disconnect() 断开连接（cdp/Browser.ts）
Page.close()	链接	单个页面	支持 runBeforeUnload 选项，会执行 beforeunload 处理

选择原则：只想清理某批匿名会话及其存储 → context.close()；任务整体结束、要释放浏览器进程 → browser.close()；只关一个标签页 → page.close()。

测试用例中的行为验证

仓库测试套件 browsercontext.test.ts 提供了三条可直接对照源码行为的验证用例：

1. 默认上下文不可关闭（L24-L37）：defaultBrowserContext().close() 必须 reject，且错误信息包含 "cannot be closed"；
2. close 后从 browserContexts() 中消失（L38-L50）：创建新上下文使列表长度 +1，close() 后恢复原长度；
3. close 连带关闭所有归属页面（L51-L65）：上下文内新增页面后，close() 会使 browser.pages() 总数回落到关闭前的水平。

小结

BrowserContext.close() 是 Puppeteer 管理隔离浏览环境的核心释放接口：它以无参异步调用销毁整个上下文及其全部页面，底层在 CDP 下经由 Target.disposeBrowserContext 命令完成，在 BiDi 下经由 userContext.remove() 完成；默认浏览器上下文被明确禁止关闭，两种协议实现都以运行时断言保证该约束。实际开发中，建议将 close() 放入 finally 块或配合 await using 使用，确保一次性上下文（尤其是承载登录态或 Cookie 的会话）在使用完毕后被可靠清理。