Puppeteer API 参考全景解读：从 Browser、Page 到 JSHandle 与 HTTPRequest 的类结构、事件模型与入口函数

本文基于 Puppeteer 官方文档站的 API Reference 总览页（仓库内对应 docs/api/index.md）编写，系统梳理 v25.x 版本 Puppeteer 公共 API 的七大类成员：Classes、Enumerations、Functions、Interfaces、Namespaces、Variables 与 Type Aliases。读完后你将能够：按"浏览器生命周期 → 页面 → 句柄 → 输入 → 网络 → 高级能力"的层次定位所需 API，理解每个核心类的职责边界与内建约束（例如构造函数为何全部标记为 internal），并知道每个符号在仓库文档体系中的落点位置，便于检索、引用与二次开发。

说明：仓库中不存在 website/versioned_docs/version-25.8.0/ 目录——历史版本的文档树是由 website/materialize-docs.ts 在构建网站时，基于 git 标签 puppeteer-v* 动态物化生成的，api/index.md 在每次发布时同步自 docs/api/index.md。因此本文以仓库内的 docs/api/index.md 作为等价主体文档，其内容与 v25.8.0 文档站的 API 总览页结构一致。

一、文档生成机制：API 总览页从哪来

docs/api/index.md 是一份由 tsdoc 工具链从源码注释自动生成的索引页（仓库中配套工具位于 tools/docgen）。它把 puppeteer-core 的公共导出按 TypeScript 声明类型归入七个板块：

1. Classes——浏览器自动化对象模型（约 48 个类）；
2. Enumerations——事件名与枚举值；
3. Functions——顶层入口函数；
4. Interfaces——各方法/事件的选项对象与数据结构（约 90 个）；
5. Namespaces——事件命名空间；
6. Variables——导出常量；
7. Type Aliases——类型别名（约 60 个）。

每个类/接口/类型都有一个对应的独立文档页（如 docs/api/puppeteer.page.md、docs/api/puppeteer.browser.md），本文的总览即按该索引的原始分类完整继承并加以扩充。

一个贯穿全文的关键约束值得先强调：几乎所有类的构造函数都标注为 internal（原文档中每个类条目末尾反复出现的 "The constructor for this class is marked as internal. Third-party code should not call the constructor directly..."）。这意味着 Puppeteer 的对象只能经由 launch()/connect() 与 Page/Browser 上的工厂方法获得，第三方代码不应直接 new 或继承这些类——这是设计 API 时保证内部状态一致性的核心手段。

二、Classes：对象模型总览

按职责划分，总览页中的类可归为八组。下表继承原文档 Classes 板块的全部条目与描述要点：

2.1 顶层入口类

类	文档页	职责
Puppeteer	puppeteer.puppeteer.md	主类。Node 环境中 import puppeteer from 'puppeteer' 得到的是其子类 PuppeteerNode 的实例，故拥有本文档全部方法以及 PuppeteerNode 的扩展方法
PuppeteerNode	puppeteer.puppeteernode.md	扩展 Puppeteer，增加 Node 特有的浏览器获取与下载行为；最常用方法是 launch()
BrowserLauncher	puppeteer.browserlauncher.md	描述"能够创建并启动浏览器实例"的启动器抽象
Configuration	puppeteer.configuration.md	定义安装与运行时配置 Puppeteer 行为的选项（puppeteer.config.js 的对应类型，仓库根目录即有示例 puppeteer.config.js）

Puppeteer 与 PuppeteerNode 的分工体现了 Puppeteer "同一 API、多运行环境"的架构：浏览器环境（如 examples/puppeteer-in-browser）只依赖 Puppeteer，Node 环境则由 PuppeteerNode 额外承担浏览器二进制下载管理（配合 docs/browsers-api/index.md 中的 @puppeteer/browsers API）。

2.2 浏览器实例与上下文

类	文档页	职责（继承原文档描述）
Browser	puppeteer.browser.md	代表一个浏览器实例，由 Puppeteer.connect() 连接或 PuppeteerNode.launch() 启动；发出 BrowserEvent 枚举定义的各种事件
BrowserContext	puppeteer.browsercontext.md	代表浏览器内的独立用户上下文；每个上下文拥有隔离的存储（cookies/localStorage 等）。页面用 window.open 打开的弹窗属于父页面的上下文。Chrome 中所有非默认上下文都是隐身（incognito）；若启动时传入 --incognito，默认上下文也可能是隐身
Target	puppeteer.target.md	代表一个 CDP target——即任何可调试对象，如 frame、page 或 worker
Extension	puppeteer.extension.md	(Experimental) 代表浏览器中已安装的扩展，可访问其 ID、名称、版本及后台 worker/页面

从源码结构看，Browser 与 BrowserContext 都实现了可释放接口（disposeSymbol/asyncDisposeSymbol 变量见第七节），支持 using/await using 语法自动清理，这与原文档中"构造器内部化"的约束相配套。

2.3 页面与 Frame

类	文档页	职责
Page	puppeteer.page.md	提供与单个标签页（或扩展后台页）交互的方法；一个 Browser 实例可对应多个 Page 实例。这是 Puppeteer API 面最大的类，文档页长达数百行
Frame	puppeteer.frame.md	代表一个 DOM frame，可类比 <iframe>：frame 可嵌套，在其中执行的 JS 不影响同环境的其他 frame。frame 生命周期由派发到父 Page 上的三个事件驱动：frameattached、framenavigated、framedetached
WebWorker	puppeteer.webworker.md	代表 Web Worker；workercreated/workerdestroyed 事件在 page 对象上发出以标记 worker 生命周期

2.4 句柄与求值

类	文档页	职责
JSHandle	puppeteer.jshandle.md	代表对页内 JavaScript 对象的引用，可通过 Page.evaluateHandle() 创建。句柄会阻止被引用对象被 GC，除非显式 dispose；当所属 frame 导航离开或父上下文销毁时自动释放。句柄可作为 Page.$eval()、Page.evaluate()、Page.evaluateHandle() 等求值函数的参数
ElementHandle	puppeteer.elementhandle.md	代表页内 DOM 元素，由 Page.$() 创建。TypeScript 下可泛型化，如 ElementHandle<HTMLSelectElement> 以获得更好的类型检查
Locator	puppeteer.locator.md	描述"定位对象并对其执行动作"的策略：若因对象未就绪导致动作失败，整个操作会被重试，各种前置条件被自动检查
Realm	puppeteer.realm.md	内部化的执行环境抽象（文档描述为空，从源码结构看是所有求值操作的底层通道）

原文档中 ElementHandle 条目附带了一段可直接运行的示例，这里完整保留：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
const hrefElement = await page.$('a');
await hrefElement.click();
// ...

2.5 输入模拟

类	文档页	职责
Keyboard	puppeteer.keyboard.md	虚拟键盘 API。高层入口是 Keyboard.type()，输入原始字符并生成正确的 keydown、keypress/input、keyup 事件；精细控制可用 Keyboard.down()、Keyboard.up()、Keyboard.sendCharacter() 手动触发事件。注意原文档提示：macOS 上 ⌘A（全选）等快捷键不可用（issue #1313）
Mouse	puppeteer.mouse.md	在主 frame 的 CSS 像素坐标系（原点在视区左上角）中操作；每个 page 对象都自带一个 Mouse，可通过 Page.mouse 访问
Touchscreen	puppeteer.touchscreen.md	暴露触摸事件（touchstart/touchmove/touchend/tap）
TouchError	puppeteer.toucherror.md	当尝试移动或结束一个不存在的触摸时抛出

配套的 *Options 类型（ClickOptions、KeyPressOptions、MouseDownOptions、MouseWheelOptions、Offset、Point、Quad 等）见第五节 Interfaces 与第六节 Type Aliases。

2.6 网络请求与响应

类	文档页	职责
HTTPRequest	puppeteer.httprequest.md	代表页面发出的 HTTP 请求。原文档说明了完整的事件时序，见下文专节
HTTPResponse	puppeteer.httpresponse.md	代表 Page 收到的响应
SecurityDetails	puppeteer.securitydetails.md	代表经安全连接收到的响应的 TLS 安全详情（issuer、protocol、SAN、有效期等）

原文档 HTTPRequest 条目的事件模型描述是理解 Puppeteer 网络拦截的钥匙，完整继承如下：

每当页面发出一个请求（例如请求某个网络资源）时，Puppeteer 的 page 会发出以下事件：

• request：请求由页面发出时；
• requestfinished：响应体下载完毕、请求完成时；

如果请求中途失败，则发出 requestfailed 而非 requestfinished。这三个事件都携带一个 HTTPRequest 实例：

page.on('request', request => ...)

注意：HTTP 错误响应（如 404、503）从 HTTP 角度看仍是"成功的响应"，请求会以 requestfinished 结束。若请求收到重定向，原请求以 requestfinished 成功结束，随后向重定向 URL 发出新请求。

此外，接口列表中还有 ContinueRequestOverrides、ResponseForRequest（request.respond() 所需的响应数据）、InterceptResolutionAction/InterceptResolutionState 枚举与 DEFAULT_INTERCEPT_RESOLUTION_PRIORITY 常量，构成"协作式请求拦截"机制的类型基础——多个拦截者可按优先级共同决定请求的续行/中止/伪造响应。

2.7 诊断与高级能力

类	文档页	职责
Accessibility	puppeteer.accessibility.md	检查浏览器可访问性树（供屏幕阅读器等辅助技术消费）。原文档解释了 Blink AX 树与平台特定 AX 树的转换关系：Puppeteer 默认近似模拟这一过滤，仅暴露"有意义"的节点
Coverage	puppeteer.coverage.md	收集页面实际使用的 JavaScript/CSS 部分信息，入口为 startJSCoverage()/startCSSCoverage()（另有内部类 CSSCoverage、JSCoverage）
Tracing	puppeteer.tracing.md	暴露 tracing 审计接口；tracing.start/tracing.stop 生成的 trace 文件可用 Chrome DevTools 或 timeline viewer 打开
CDPSession	puppeteer.cdpsession.md	与原始 Chrome DevTools Protocol 对话的通道；用 CDPSession.send() 调协议方法，用 CDPSession.on 订阅协议事件
Connection	puppeteer.connection.md	内部连接抽象（仅"构造器 internal"说明）
ConnectionTransport	puppeteer.connectiontransport.md	传输层接口（send/close）
ConsoleMessage	puppeteer.consolemessage.md	通过 page 的 console 事件派发的控制台消息对象，含 type、text、location、args、stackTrace 等
DeviceRequestPrompt	puppeteer.devicerequestprompt.md	响应页面通过 WebBluetooth 等 API 请求设备的提示框，由 Page.waitForDevicePrompt() 返回，支持 select/cancel/waitForDevice
Dialog	puppeteer.dialog.md	通过 page 的 dialog 事件派发，支持 accept/dismiss
FileChooser	puppeteer.filechooser.md	响应页面文件选择请求，由 Page.waitForFileChooser() 返回。原文档提醒：同一时间只能有一个文件选择器打开，且每个选择器都必须 accept 或 cancel，否则会阻塞后续选择器出现
ScreenRecorder / ScreenRecording	puppeteer.screenrecorder.md / puppeteer.screenrecording.md	屏幕录制（配合 Page.record() 与 ScreencastOptions 实验性选项）
WebMCP / WebMCPTool / WebMCPToolCall	puppeteer.webmcp.md 等	(Experimental) WebMCP API：读取/执行页面上注册的 MCP 工具，配套事件 WebMCPToolsAddedEvent/WebMCPToolsRemovedEvent
BluetoothEmulation	puppeteer.bluetoothemulation.md	(Experimental) Web Bluetooth 仿真。原文档特别指出局限：规范要求仿真适配器按顶层可导航对象隔离，但当前 Chromium 实现绑定在 browser context 上，同上下文中不同页面的蓝牙仿真状态会互相干扰

2.8 错误类层级

类	文档页	抛出场景
PuppeteerError	puppeteer.puppeteererror.md	所有 Puppeteer 特有错误的基类
ProtocolError	puppeteer.protocolerror.md	协议层出现错误时
ConnectionClosedError	puppeteer.connectionclosederror.md	底层协议连接被关闭时
TimeoutError	puppeteer.timeouterror.md	操作因超时终止时，如 page.waitForSelector、puppeteer.launch
UnsupportedOperation	puppeteer.unsupportedoperation.md	当前使用的协议不支持该方法时
TouchError	puppeteer.toucherror.md	移动/结束不存在的触摸时

排错时建议先按此层级捕获：TimeoutError 通常指向等待条件不满足；ProtocolError/ConnectionClosedError 指向浏览器进程或协议会话异常；UnsupportedOperation 提示所选协议（CDP 与 WebDriver BiDi 双协议架构）下该方法不可用。

三、Enumerations：事件枚举

Enumerations 板块收录 8 个枚举，其中"事件枚举"是与 EventEmitter 配套的核心：

枚举	文档页	含义
BrowserEvent	puppeteer.browserevent.md	浏览器实例可能发出的全部事件（如 disconnected、targetcreated 等）
BrowserContextEvent	puppeteer.browsercontextevent.md	上下文级事件（targetcreated/targetdestroyed 等）
PageEvent	puppeteer.pageevent.md	page 实例可能发出的全部事件，含 console、dialog、request/requestfinished/requestfailed、filechooser、deviceprompt、frame 三事件、workercreated/workerdestroyed、download 等
LocatorEvent	puppeteer.locatorevent.md	locator 实例可能发出的事件
InterceptResolutionAction	puppeteer.interceptresolutionaction.md	协作式拦截的解决动作
TargetType	puppeteer.targettype.md	target 类型
WebWorkerEvent	puppeteer.webworkerevent.md	worker 事件
AutofillAddressField	puppeteer.autofilladdressfield.md	支持的 autofill 地址字段名（配合 ElementHandle.autofill()）

与事件枚举平行的还有一组 *Events 接口（BrowserEvents、BrowserContextEvents、CDPSessionEvents、PageEvents、FrameEvents、LocatorEvents、WebWorkerEvents），它们定义了各事件回调的载荷类型。原文档 PageEvents 条目说明：它"标注了 page 事件回调函数接收的对象"，事件本身的触发时机见 PageEvent。

四、Functions：四个顶层入口

Functions 板块列出 API 总入口，是日常使用频率最高的四个符号：

函数	文档页	用途
connect(options)	puppeteer.connect.md	连接一个已存在的浏览器实例（经 WebSocket 端点），参数类型见 ConnectOptions——"启动任意浏览器或连接已存在浏览器实例时可传的通用浏览器选项"，底层 WebSocket 选项为 WsOptions（原文档注明仅用于 Node.js 环境）
defaultArgs(options?)	puppeteer.defaultargs.md	计算默认命令行参数，供自定义 executablePath/pipe 场景复用
launch(options?)	puppeteer.launch.md	启动并连接一个新浏览器实例，参数类型 LaunchOptions——"启动任意浏览器时可传的通用启动选项"
trimCache()	puppeteer.trimcache.md	裁剪本地浏览器下载缓存，回收已不在保留策略内的旧版本浏览器

最小闭环示例（与 ElementHandle 条目中的示例一致）：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch(); // launch() 启动并连接
const page = await browser.newPage();
await page.goto('https://example.com');
const href = await page.$('a');
await href?.click();
await browser.close();

若要连接远端浏览器，则换成 puppeteer.connect({browserWSEndpoint})，两者最终都得到 Browser 实例——这就是 docs/api/puppeteer.browser.md 中"connected via Puppeteer.connect() or launched by PuppeteerNode.launch()"两条来路的含义。

五、Interfaces：选项对象与数据结构

Interfaces 板块约 90 个条目，是 API 的参数面。按用途归类（均继承原文档列表与描述）：

启动/连接与配置：Configuration（安装与运行时配置）、LaunchOptions、ConnectOptions、ChromeSettings、ChromeHeadlessShellSettings、FirefoxSettings、ExperimentsConfiguration（实验特性开关）、SupportedWebDriverCapabilities（Puppeteer 自身不设置的 WebDriver BiDi 能力）。

页面操作选项：GoToOptions（page.goto()）、ReloadOptions、SetContentWaitForOptions、FrameAddScriptTagOptions、FrameAddStyleTagOptions、FrameWaitForFunctionOptions、ScreenshotOptions、ElementScreenshotOptions、ScreenshotClip、PDFOptions、PDFMargin、HeapSnapshotOptions（Page.captureHeapSnapshot()）、TracingOptions、RecordOptions（实验性）、ScreencastOptions（实验性）、SnapshotOptions（accessibility snapshot）、WaitForOptions、WaitForSelectorOptions、WaitForNetworkIdleOptions、WaitForTargetOptions、WaitTimeoutOptions、CreatePageOptions、GeolocationOptions、MediaFeature、NetworkConditions、InternalNetworkConditions、CommandOptions（实验性命令执行）、ActionOptions、QueryOptions（选择器查询）。

等待/可见性：VisibilityOption 类型说明"等待元素 visible 还是 hidden，null 关闭可见性检查"；FrameWaitForFunctionOptions 控制 waitForFunction 的轮询。

Cookie 族：Cookie（cookie 对象）、CookieData（浏览器级 cookies API 的设置参数）、CookieParam（页面级 cookies API 的设置参数）、CookiePartitionKey（Chrome 分区 cookie 键）、DeleteCookiesRequest。类型别名还有 CookiePriority、CookieSameSite（含数字后缀 _2 后缀是 tsdoc 对同名去重的产物）、CookieSourceScheme。

输入几何：BoundingBox、BoxModel、Point、Offset、ClickOptions、MouseClickOptions、MouseMoveOptions、MouseOptions、MouseWheelOptions、KeyboardTypeOptions、KeyDownOptions、KeyPressOptions、LocatorClickOptions、LocatorFillOptions、LocatorScrollOptions、TouchHandle（操作已启动触摸的接口）。

网络：ContinueRequestOverrides（request.continue() 的重写项）、ResponseForRequest（伪造响应所需数据）、RemoteAddress、DownloadBehavior、DownloadPolicy。

PWA 族：InstallPWAOptions（Browser.installPWA()）、LaunchPWAOptions（Browser.launchPWA()）、UninstallPWAOptions（Browser.uninstallPWA()）、GetPWAStateOptions（Browser.getPWAState()）及数据结构 PWAState、PWADisplayMode（用户偏好独立窗口还是标签页打开）。

多屏：AddScreenParams、ScreenInfo、ScreenOrientation（_2 后缀）、WorkAreaInsets、WindowBounds、WindowState、WindowId——支撑 Browser.addScreen()/removeScreen()/screens/窗口边界控制。

蓝牙仿真：BluetoothEmulation（实验性接口）、BluetoothManufacturerData、PreconnectedPeripheral、AdapterState。

Autofill：AutofillAddressField（枚举）、AutofillData、Credentials（Page.authenticate()）。

事件载荷与传输：ConsoleMessageLocation、BrowserContextEvents、BrowserEvents、CDPSessionEvents、PageEvents、FrameEvents、LocatorEvents、WebWorkerEvents、ConnectionTransport（send/close 传输接口）、CommonEventEmitter（on/off/once/removeAllListeners/listenerCount 的公共监听器接口）、TargetFilterCallback、Handler。

序列化/调试：SerializedAXNode（可访问性节点及其相关属性）、DebugInfo（实验性）、Issue（"代表一个 DevTools issue"）、NewDocumentScriptEvaluation（evaluateOnNewDocument 返回的评估句柄）、CustomQueryHandler（自定义查询处理器协议）、PuppeteerLifeCycleEvent（实验性生命周期事件）、ResourceType 类型别名。

其他：Metrics（page.metrics() 的性能指标）、Quad、WritableDestination（流式写目标，write/end，配合 createPDFStream()/record()）、EventEmitter 相关的 EventWithWildcard、EventsWithWildcard、EventType、InnerParams。

六、Variables 与 Namespaces

Variables 板块共 9 个导出常量：

变量	文档页	说明
puppeteer	puppeteer.puppeteer.md	默认导出实例
executablePath	puppeteer.executablepath.md	浏览器可执行文件路径
KnownDevices	puppeteer.knowndevices.md	供 Page.emulate() 使用的设备列表
PredefinedNetworkConditions	puppeteer.predefinednetworkconditions.md	供 Page.emulateNetworkConditions() 使用的预定义网络条件（如 3G/4G 限速档）
MouseButton	puppeteer.mousebutton.md	合法鼠标按键枚举值（同时出现在 Type Aliases 板块）
DEBUG_PREFIXES	puppeteer.debug_prefixes.md	(Experimental) 调试日志前缀
DEFAULT_INTERCEPT_RESOLUTION_PRIORITY	puppeteer.default_intercept_resolution_priority.md	协作式请求拦截的默认解决优先级
disposeSymbol / asyncDisposeSymbol	puppeteer.disposesymbol.md / puppeteer.asyncdisposesymbol.md	符号处置协议常量，支撑 using/await using 资源管理

Namespaces 板块仅一项：CDPSessionEvent（puppeteer.cdpsessionevent.md），描述 CDPSession 类发出的事件（sessionattached/sessiondetached 等）。

七、Type Aliases：类型别名速览

Type Aliases 板块约 60 项，覆盖以下语义域：

• 异步工具：Awaitable、AwaitableIterable、AwaitablePredicate、AwaitedLocator、Predicate——Puppeteer 大量方法返回"可 await 且可迭代"的联合类型，这组别名是其类型系统基石。

• 求值：EvaluateFunc、EvaluateFuncWith、HandleFor、NodeFor、ElementFor、HandleOr、FlattenHandle、NodeFor——page.evaluate(fn, ...args) 中参数与返回值的类型映射规则。

• 浏览器/协议：SupportedBrowser（"Puppeteer 支持的浏览器"）、ChromeReleaseChannel、ProtocolType、ProtocolLifeCycleEvent（导航生命周期档位，如 domcontentloaded、networkidle）、PuppeteerLifeCycleEvent（实验性）、CDPEvents、TargetFilterCallback。

• Cookie：CookiePriority、CookieSameSite（原文档分别注明对应 IETF 草案 cookie-priority 与 first-party-cookies）、CookieSourceScheme（"值为 Unset 时允许协议客户端模拟旧版 scheme cookie 作用域，这是临时能力，未来会移除"）。

• 输入：KeyInput（"所有可传给接收用户输入函数（如 keyboard.press）的合法按键"）、ImageFormat、VideoFormat（录制/截图格式）。

• 打印：PaperFormat 及其小写变体 LowerCasePaperFormat。原文档给出了全部纸张尺寸，完整保留：

  • Letter: 8.5in x 11in / 21.59cm x 27.94cm
  • Legal: 8.5in x 14in / 21.59cm x 35.56cm
  • Tabloid: 11in x 17in / 27.94cm x 43.18cm
  • Ledger: 17in x 11in / 43.18cm x 27.94cm
  • A0: 33.1102in x 46.811in / 84.1cm x 118.9cm
  • A1: 23.3858in x 33.1102in / 59.4cm x 84.1cm
  • A2: 16.5354in x 23.3858in / 42cm x 59.4cm
  • A3: 11.6929in x 16.5354in / 29.7cm x 42cm
  • A4: 8.2677in x 11.6929in / 21cm x 29.7cm
  • A5: 5.8268in x 8.2677in / 14.8cm x 21cm
  • A6: 4.1339in x 5.8268in / 10.5cm x 14.8cm

• 事件/日志：ConsoleMessageType（支持的控制台消息类型）、EventType、EventWithWildcard、EventsWithWildcard、Logger（(Experimental) 日志工厂函数：接收调试通道前缀并返回输出该通道日志的 LoggerFunction，禁用时返回 undefined）、LoggerFunction、DebugPrefix、ExperimentsConfiguration。

• 权限：Permission（已标记 Deprecated）、PermissionState、PermissionDescriptor。

• 其他：ActionResult、BoundingBox/BoxModel/Quad/Point/Offset/Metrics/RemoteAddress/RemoteAddress、ResourceType（"渲染引擎视角的 HTTPRequest 资源类型"）、VisibilityOption、MouseButton、SupportedWebDriverCapability、DownloadPolicy、InnerParams、Mapper、AdapterState、AutofillData、CreatePageOptions、GetPWAStateOptions、InstallPWAOptions、LaunchPWAOptions、UninstallPWAOptions、HeapSnapshotOptions、SetContentWaitForOptions、WaitTimeoutOptions、ErrorCodes/ErrorCode、WebSocket 相关的 WsOptions（已在 Functions 节提及）、WindowId、WindowState、WorkAreaInsets、ScreenshotClip、SnapshotOptions。

八、如何检索与使用这套 API

1. 入口先行：任何任务从 launch()/connect() 得到 Browser，再 newPage() 得到 Page；Page 上聚合了 keyboard/mouse/touchscreen/accessibility/coverage/tracing/webmcp 等子对象，以及 frames()/mainFrame()/workers() 的枚举接口。
2. 事件驱动：监听器统一走 EventEmitter 的 on/off/once（见 puppeteer.eventemitter.md），事件名以 BrowserEvent/PageEvent 等枚举为权威清单，回调载荷以对应 *Events 接口为准。
3. 句柄要释放：JSHandle/ElementHandle 会阻止 GC，导航离开或上下文销毁时自动释放；长生命周期脚本建议显式 dispose 或使用 using 声明（disposeSymbol/asyncDisposeSymbol 的存在即为此服务）。
4. 错误分级：按"二、2.8"的层级捕获，TimeoutError 是自动化脚本中最常见的失败信号。
5. 版本对照：文档版本与浏览器版本绑定，仓库根目录 versions.json 记录了每个 Puppeteer 发布对应的 Chrome/Firefox 版本（v25.x 系列对应 Chrome 148–152 与 Firefox stable 150–155），docs/supported-browsers.md 提供按版本生成后的支持矩阵，docs/api/index.md 中所有条目均以仓库当前 puppeteer-core 的 TypeScript 声明为准。

至此，docs/api/index.md 中的七大板块——48 个类、8 个枚举、4 个顶层函数、约 90 个接口、1 个命名空间、9 个变量与约 60 个类型别名——已全部按原文档分类继承并逐条归位。任何单个符号的完整签名、参数与示例，可沿文中链接进入对应的 docs/api/puppeteer.*.md 详情页查阅。