Puppeteer Browser 事件体系详解：BrowserEvents 接口与 4 个核心浏览器事件

在 Puppeteer 中，Browser 对象是所有页面、浏览器上下文与 Target 的入口，它的生命周期与内部目标（tab、worker 等）的增删都会以事件形式对外广播。本文围绕 BrowserEvents 接口定义 展开，逐一讲解 disconnected、targetcreated、targetdestroyed、targetchanged 四个事件的语义、载荷类型与触发时机，并结合 puppeteer-core 源码 说明事件在 CDP 与 WebDriver BiDi 两种协议下的真实派发链路，最后给出可运行的监听示例与测试佐证。读完本文，你可以准确地在自动化脚本中感知浏览器断连、拦截新窗口打开、追踪页面销毁，并理解 browser.waitForTarget() 的底层实现原理。

BrowserEvents 接口：事件名到载荷类型的类型契约

根据 docs/api/puppeteer.browserevents.md，该接口的签名非常简单：

export interface BrowserEvents extends Record<EventType, unknown>

Extends: Record<EventType, unknown>

它继承自 Record<EventType, unknown>，即“任意事件名到任意未知载荷”的映射，而其真正有价值的是为四个具体事件名提供了精确的载荷类型标注：

事件属性	载荷类型	说明
disconnected	undefined	浏览器断连时无任何载荷
targetchanged	Target	携带发生 URL 变化的 Target 实例
targetcreated	Target	携带新创建的 Target 实例
targetdestroyed	Target	携带被销毁的 Target 实例

从源码看，这一接口并非孤立的类型定义。在 api/Browser.ts 中，与接口配套的 BrowserEvent 常量枚举定义了事件名的字符串字面量：

export const enum BrowserEvent {
  Disconnected = 'disconnected',
  TargetChanged = 'targetchanged',
  TargetCreated = 'targetcreated',
  TargetDestroyed = 'targetdestroyed',
  /** @internal */
  TargetDiscovered = 'targetdiscovered',
}

注意源码中还存在第五个事件 TargetDiscovered = 'targetdiscovered'，其载荷为原始的 Protocol.Target.TargetInfo，并明确标注 @internal——它是 CDP 协议层在 Target 真正初始化之前发出的内部探测事件，不面向公开 API 使用。

BrowserEvents 接口的消费者是 Browser 抽象基类本身：

export abstract class Browser extends EventEmitter<BrowserEvents> { ... }

（见 api/Browser.ts#L478）。由于 Browser 直接继承泛型化的 EventEmitter<BrowserEvents>，你在 TypeScript 中调用 browser.on('targetcreated', target => ...) 时，回调参数会被自动推导为 Target 类型，无需手动断言——这正是 BrowserEvents 接口存在的意义：它是事件监听回调的类型安全来源。

四个事件逐一详解

以下说明综合了 BrowserEvent 枚举文档 的描述与源码中的派发位置。

disconnected：浏览器断连信号

触发时机：当 Puppeteer 与浏览器实例失去连接时触发。官方文档指出这只有两种成因：

• 浏览器进程关闭或崩溃；
• 显式调用了 Browser.disconnect()。

载荷：undefined，监听回调不带参数。

从 CDP 实现看（cdp/Browser.ts#L202-L210），disconnected 是底层通信会话断开的直接映射：

#emitDisconnected = () => {
  this.emit(BrowserEvent.Disconnected, undefined);
};

// _attach() 内部：
connectionEmitter.on(CDPSessionEvent.Disconnected, this.#emitDisconnected);

即底层 CDPSession 一断开（无论原因），Browser 就同步发出 disconnected。在 BiDi 实现中则是监听浏览器核心对象的 disconnected 事件后重发，并清空所有监听器（bidi/Browser.ts#L187-L190）。

典型用法是配合重连：先保存 browser.wsEndpoint()，在 disconnected 回调里通过 Puppeteer.connect 重建连接：

const browser = await puppeteer.launch();
const endpoint = browser.wsEndpoint();

browser.on('disconnected', () => {
  console.log('浏览器已断开，可尝试用 endpoint 重连');
  // puppeteer.connect({browserWSEndpoint: endpoint})
});

targetcreated：Target 创建事件

触发时机：当一个 Target 被创建时触发，典型场景包括：

• 页面内调用 window.open() 打开了新窗口/新标签页；
• 调用 browser.newPage() 创建新页面。

载荷：Target 实例。

作用域：官方文档特别强调——该事件覆盖所有浏览器上下文中的 target 创建。

CDP 实现中（cdp/Browser.ts#L373-L382），事件由内部 TargetManager 的 TargetAvailable 事件驱动，且有一个关键的前置条件：只有当 target 完成初始化且状态为 SUCCESS 时才发出，初始化中途失败的 target 不会触发该事件：

#onAttachedToTarget = async (target: CdpTarget) => {
  if (
    target._isTargetExposed() &&
    (await target._initializedDeferred.valueOrThrow()) ===
      InitializationStatus.SUCCESS
  ) {
    this.emit(BrowserEvent.TargetCreated, target);
    target.browserContext().emit(BrowserContextEvent.TargetCreated, target);
  }
};

注意源码中每个 target 级事件都会同时向浏览器级（BrowserEvent）和上下文级（BrowserContextEvent）各派发一次。如果你只关心某个隔离上下文内的新页面，应监听 browserContext 而不是 browser。

targetdestroyed：Target 销毁事件

触发时机：当一个 Target 被销毁时触发，例如页面被关闭。

载荷：Target 实例。

作用域：同样覆盖所有浏览器上下文。

CDP 实现中对应 TargetManager 的 TargetGone 事件（cdp/Browser.ts#L384-L395），与 targetcreated 对称：先解析 target 的初始化 Deferred，仅对初始化成功的 target 发出销毁事件。一个常见用途是统计页面存活时长或感知弹窗被用户手动关闭：

const created = await new Promise<Target>(resolve =>
  browser.on('targetcreated', t => {
    if (t.type() === 'page') resolve(t);
  }));
browser.once('targetdestroyed', t => {
  if (t === created) console.log('目标页面已关闭');
});

targetchanged：Target URL 变化事件

触发时机：当某个 Target 的 URL 发生变化时触发，例如页面开始导航、发生重定向。

载荷：Target 实例。

作用域：覆盖所有浏览器上下文。

源码中它由 TargetManager 的 TargetChanged 事件直接驱动（cdp/Browser.ts#L397-L400），没有初始化状态的前置判断，因此一次导航过程中可能伴随多个 targetchanged。需要说明的是，该事件的粒度是 target 信息变化（最典型的就是 URL 变化），文档表述为 "when the URL of a target changes"。

targetchanged 最重要的实战价值在于它是 browser.waitForTarget() 的两大事件来源之一（详见下文）。

源码级派发链路：CDP 与 BiDi 的差异

Puppeteer 当前同时支持 Chrome DevTools Protocol（CDP）与 WebDriver BiDi 两套协议，两套实现的 Browser 都遵循同一个 BrowserEvents 契约，但派发路径不同：

CDP 路径（cdp/Browser.ts#L206-L234）：_attach() 阶段把四类来源统一挂到事件系统上：

底层来源	映射到的 BrowserEvent
CDPSessionEvent.Disconnected	disconnected
TargetManagerEvent.TargetAvailable	targetcreated
TargetManagerEvent.TargetGone	targetdestroyed
TargetManagerEvent.TargetChanged	targetchanged
TargetManagerEvent.TargetDiscovered	targetdiscovered（内部）

BiDi 路径（bidi/Browser.ts#L181-L247）：disconnected 由 browserCore.once('disconnected') 触发；三个 target 事件则采用了“上下文聚合”模式——BidiBrowser 为每个 BidiBrowserContext 注册 trustedEmitter 监听，把上下文级的 BrowserContextEvent.TargetCreated/Changed/Destroyed 逐层向上重发为浏览器级 BrowserEvent，从而保证“browser 级事件覆盖所有上下文”的语义在两种协议下行为一致。

实战：waitForTarget 如何用这些事件实现

Browser 抽象类内置的 waitForTarget 是这四个事件最直接的消费者，其实现（api/Browser.ts#L608-L623）清晰地展示了事件如何转化为“等待某个条件成立”的 Promise：

async waitForTarget(
  predicate: (x: Target) => boolean | Promise<boolean>,
  options: WaitForTargetOptions = {},
): Promise<Target> {
  const {timeout: ms = 30000, signal} = options;
  return await firstValueFrom(
    merge(
      fromEmitterEvent(this, BrowserEvent.TargetCreated),
      fromEmitterEvent(this, BrowserEvent.TargetChanged),
      from(this.targets()),
    ).pipe(
      filterAsync(predicate),
      raceWith(fromAbortSignal(signal), timeout(ms)),
    ),
  );
}

可以拆解出三个要点：

1. 三路合并：同时订阅 targetcreated 与 targetchanged 事件，并把当前已存在的 this.targets() 快照也作为候选，因此调用时已经存在的 target 同样能被匹配到；
2. 默认超时 30 秒，可通过 options.timeout 修改（传 0 禁用），也支持 AbortSignal 取消；
3. 命中即返回第一个匹配的 Target。

文档给出的标准示例（捕获 window.open 打开的新窗口）即基于此：

await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browser.waitForTarget(
  target => target.url() === 'https://www.example.com/',
);

注意一个细节：由于合并流中同时包含 targetchanged，当 window.open 的 URL 是在 target 创建之后才填充时，靠 URL 匹配的新窗口同样能被捕获——这正是同时订阅两个事件而非仅 targetcreated 的原因。

测试用例对事件行为的佐证

仓库测试套件对以上事件有直接断言，可作为行为事实的补充证据：

• test/src/launcher.test.ts#L955-L999 中的 Browser.Events.disconnected 用例验证了 disconnected 在浏览器关闭、连接断开、底层 WebSocket 关闭三种情形下都会发出，并且本地连接与两个远端连接上的监听器各自独立计数；
• test/src/target.test.ts 中大量使用了 waitEvent(browser, 'targetcreated')、waitEvent(context, 'targetdestroyed')、waitEvent(context, 'targetchanged') 等调用（如 target.test.ts#L148、target.test.ts#L277-L308），覆盖页面创建、关闭、导航等生命周期，印证了 browser 级与 browserContext 级事件并行派发的设计。

小结与延伸阅读

BrowserEvents 接口本身只有短短四行类型标注，但它是理解 Puppeteer 浏览器层事件模型的入口：disconnected 负责连接健康监控与重连，targetcreated/targetdestroyed/targetchanged 三者构成 target 完整生命周期的观测点，且均跨越所有浏览器上下文；browser.waitForTarget() 则展示了如何把这些事件组合成开箱即用的异步等待。

如需继续深入，可参考以下仓库内文档：

• BrowserEvent 枚举文档：四个事件的完整语义描述；
• Browser 类文档：事件宿主类的全部方法（newPage、targets、waitForTarget、disconnect 等）；
• Target 类文档：事件载荷类型 Target 的 type()、url()、page() 等方法；
• BrowserContextEvents 文档：与 browser 级事件一一对应的上下文级事件，适合只关注单个隔离上下文的场景。