Puppeteer API Reference 指南：核心类、入口函数与类型系统的完整导读

API Reference 索引文档是 Puppeteer（JavaScript API for Chrome and Firefox）TypeScript 公共 API 面的总目录：它把 puppeteer 命名空间下所有可导出的类、枚举、函数、接口、变量与类型别名按符号分类罗列，并给出每个符号的一句话职责说明。读完本文，你可以建立一张"符号 → 职责 → 源码位置"的地图，知道在写自动化、做网络拦截、处理事件或生成 PDF/截图时该查阅哪个类型，以及如何对照仓库源码验证这些 API 的真实实现。

一、Reference 的整体结构：七类符号如何组织

索引文档按 TypeScript API 报告的标准分节组织，共七类符号：

分节	内容	数量级
Classes	可实例化/可扩展的运行时对象，如 Browser、Page、ElementHandle	40+
Enumerations	事件名与取值集合，如 PageEvent、BrowserEvent	8
Functions	顶层入口函数，如 launch(options)、connect(options)	4
Interfaces	选项与数据结构接口，如 LaunchOptions、ClickOptions、Viewport	100
Namespaces	事件映射命名空间，如 CDPSessionEvent	1
Variables	常量与单例，如 KnownDevices、PredefinedNetworkConditions、puppeteer	9
Type Aliases	工具类型与取值联合，如 Awaitable、KeyInput、PaperFormat	70+

这一结构与仓库源码的组织方式一一对应：packages/puppeteer-core/src/api/ 下的 api.ts 桶文件 集中再导出 Browser、BrowserContext、CDPSession、Dialog、ElementHandle、Frame、HTTPRequest、HTTPResponse、Input（Keyboard/Mouse/Touchscreen）、JSHandle、Page、Realm、Target、WebWorker、locators 等 API 类，正是索引中 Classes 分节的来源；顶层函数则由 packages/puppeteer/src/puppeteer.ts 从 PuppeteerNode 单例上解构导出 connect、defaultArgs、executablePath、launch、trimCache、setFollowSymlinks 并 export default puppeteer。

一个贯穿全文档的约定值得先说明：索引中几乎所有类都标注了"The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses"。从源码结构看，这些类的构造函数确实仅供内部装配使用，公开用法永远是通过 launch()/connect()/page.$()/evaluateHandle() 等工厂路径获得实例。

二、核心运行时类：Browser 到 Target 的对象模型

2.1 浏览器层：Browser、BrowserContext、Target、WebWorker

• Browser：代表一个浏览器实例，来源于 Puppeteer.connect() 或 PuppeteerNode.launch()；其可发射的事件由 BrowserEvent 枚举 描述。
• BrowserContext：代表浏览器内的"用户上下文"。浏览器启动时至少有一个默认上下文，其余可通过 Browser.createBrowserContext() 创建，每个上下文拥有隔离的存储（cookies/localStorage 等）。弹窗（如 window.open）归属于父页面所在的上下文。文档特别备注：在 Chrome 中所有非默认上下文都是 incognito；若以 --incognito 参数启动，默认上下文也可能是 incognito。其事件由 BrowserContextEvent 描述。
• Target：对应 CDP 中的 target 概念——一切"可被调试的东西"，如 frame、page、worker。
• WebWorker：代表一个 Web Worker；workercreated/workerdestroyed 事件在 page 对象上发射以标记 worker 生命周期。
• BrowserLauncher：描述"能创建并启动浏览器实例的类"。从源码看，PuppeteerNode.ts 的 #getLauncher() 会在 chrome 与 firefox 之间选择 ChromeLauncher 或 FirefoxLauncher，这正是接口在实现层的落点。

2.2 页面与 DOM：Page、Frame、ElementHandle、JSHandle、Realm

• Page：与浏览器中单个标签页（或扩展后台页）交互的核心类；一个 Browser 实例可能持有多个 Page。
• Frame：代表一个 DOM frame，可类比为可嵌套的 <iframe>；在某个 frame 中执行的 JavaScript 不影响其环境 frame 内的其他 frame。frame 生命周期由三个在父 page 上派发的事件控制：PageEvent.FrameAttached → PageEvent.FrameNavigated → PageEvent.FrameDetached（见 PageEvent）。
• ElementHandle：代表页内一个 DOM 元素，可由 Page.$() 创建，文档给出的标准示例：

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();
// ...

关键语义：ElementHandle 会阻止其 DOM 元素被垃圾回收，直到 handle 被 dispose；当所属 frame 导航离开或父上下文销毁时自动释放；可作为 Page.$eval()/Page.evaluate() 的参数；TypeScript 下支持泛型 ElementHandle<HTMLSelectElement> 以获得更精确的类型检查。

• JSHandle：代表对 JavaScript 对象的引用，可由 Page.evaluateHandle() 创建；同样阻止被引用对象被 GC，且可用作各类求值函数的参数并解析为被引用对象。
• Realm：从源码结构看，Page 同时持有 CDP 与 BiDi 两套实现路径，Realm 是其中对"可执行 JS 的隔离环境"的抽象（Page.ts 的导入清单即可印证其核心地位）。

2.3 输入模拟：Keyboard、Mouse、Touchscreen

• Keyboard：虚拟键盘 API。高层入口 Keyboard.type() 接收原始字符并生成完整的 keydown、keypress/input、keyup 事件序列；精细控制可用 Keyboard.down()、Keyboard.up()、Keyboard.sendCharacter()。文档备注指出 macOS 上 ⌘ A 这类快捷键不生效（上游 issue #1313）。
• Mouse：在主 frame 的 CSS 像素坐标系（原点为视口左上角）内操作；每个 page 都有独立的 page.mouse。
• Touchscreen：暴露触屏事件；配套的 TouchError 在尝试移动/结束一个不存在的 touch 时抛出。

2.4 网络层：HTTPRequest、HTTPResponse、SecurityDetails

• HTTPRequest：代表页面发出的 HTTP 请求。文档给出了完整的事件语义：页面每发出一个请求，page 会发射 request（请求发出时）与 requestfinished（响应体下载完成）；若中途失败则改为发射 requestfailed。注意两点边界：HTTP 错误响应（404/503）在协议层面仍是"成功"的响应，会以 requestfinished 完成；发生重定向时原请求以 requestfinished 结束，并向新 URL 发起新请求。
• HTTPResponse：代表 Page 收到的响应对象。
• SecurityDetails：代表经由安全连接收到的响应的安全细节（证书、协议等）。

2.5 协议层：CDPSession、Connection 与错误族

• CDPSession：用于直接说"原始 Chrome DevTools Protocol"；协议方法经 CDPSession.send() 调用，协议事件经 CDPSession.on 订阅。
• Connection 与 ConnectionClosedError（底层协议连接关闭时抛出）、ProtocolError（协议层错误）构成协议错误处理链。
• 通用错误族：所有 Puppeteer 自定义错误继承自 PuppeteerError；TimeoutError 在 page.waitForSelector、puppeteer.launch 等操作因超时终止时抛出；UnsupportedOperation 在当前协议不支持某方法时抛出（例如在 BiDi 协议下调用 CDP 专属能力）。

2.6 事件与交互对象：EventEmitter、Dialog、FileChooser、DeviceRequestPrompt、ConsoleMessage

• EventEmitter：多数 Puppeteer 类共同继承的事件基类，日常主要使用其 on/off 方法。
• Dialog：由 Page 经 dialog 事件派发的对话框实例（alert/confirm 等）。
• FileChooser：响应页面发起的文件选择；由 Page.waitForFileChooser() 返回。文档强调：浏览器同一时刻只能打开一个文件选择器，且所有 chooser 必须 accept 或 cancel，否则后续 chooser 将不再出现。
• DeviceRequestPrompt：响应页面通过 WebBluetooth 等 API 发起的设备请求，由 Page.waitForDevicePrompt() 返回；配套的 DeviceRequestPromptDevice 表示请求中的设备。
• ConsoleMessage：由 page 经 console 事件派发的控制台消息；ConsoleMessageType 列出支持的类型。

2.7 分析类：Accessibility、Coverage、Tracing、ScreenRecorder

• Accessibility：提供检查浏览器无障碍树的方法。文档的备注信息量很大：无障碍树是高度平台相关的；Blink（Chrome 渲染引擎）有"accessibility tree"概念，再翻译成各平台特定 API；Puppeteer 默认会近似模拟这一过滤过程，只暴露"有意思"的节点。
• Coverage：采集页面实际使用到的 JS/CSS 部分；报告条目为 CoverageEntry；JSCoverage 与 CSSCoverage 分别是 JavaScript 与 CSS 的具体实现，选项见 JSCoverageOptions/CSSCoverageOptions。
• Tracing：暴露 tracing 审计接口；用 tracing.start/tracing.stop 生成的 trace 文件可在 Chrome DevTools 或 timeline viewer 中打开。
• ScreenRecorder：对应 Node 侧的屏幕录制实现（ScreenRecorder.ts），支持 AsyncDisposable（见变量表中的 asyncDisposeSymbol）。

2.8 实验性（Experimental）符号

索引中显式标注实验性的 API 包括：Extension（已安装浏览器扩展的表示，可访问其 ID/名称/版本及后台 worker 与页面）、ExtensionTransport（当 Puppeteer 运行在扩展环境内时经 chrome.debugger API 建立连接，并为受限的 CDP 补齐缺失命令与事件）、WebMCP 及其配套的 WebMCPTool/WebMCPToolCall、BluetoothEmulation（注意其备注：Chromium 的蓝牙模拟目前绑定在 browser context 而非 page 上，同一上下文中不同页面的模拟会互相干扰）、ScreencastOptions、DebugInfo、Logger/LoggerFunction。使用实验性 API 时应假定其签名可能在后续版本变化。

三、顶层函数与 Puppeteer / PuppeteerNode 双入口

索引 Functions 分节列出四个入口函数：connect(options)、defaultArgs(options)、launch(options)、trimCache()，分别有独立文档页 puppeteer.connect.md、puppeteer.defaultargs.md、puppeteer.launch.md、puppeteer.trimcache.md。

• Puppeteer：主类，承载所有环境共有的能力（如 connect()）以及静态的自定义查询处理器 API。从 common/Puppeteer.ts 可见，它还提供了 registerCustomQueryHandler/unregisterCustomQueryHandler/customQueryHandlerNames/clearCustomQueryHandlers 四个静态方法：注册后，选择器字符串加上 <name>/ 前缀即可使用该处理器（例如 page.$('text/…')）。
• PuppeteerNode：在 Node 环境下 import puppeteer from 'puppeteer' 得到的实例类型，扩展了浏览器下载/获取行为；最常用的方法是 launch。从源码看，puppeteer.ts 直接构造了一个 PuppeteerNode 单例并注入 getConfiguration，这就是"模块导入即得实例"的实现；而 PuppeteerNode.ts 中的 launch() 会解析 browser 选项（默认 chrome）并委派给对应 launcher。
• executablePath：索引同时把它列为 Function 与 Variable，源码中它是 PuppeteerNode 的重载方法——无参（返回最近启动浏览器的路径）、传 channel 或传 LaunchOptions 三种签名。
• trimCache()：按当前配置清理缓存目录中非当前版本的 Chrome/Firefox 二进制；文档明确提示它不会检查同一缓存目录上其他 Puppeteer 版本是否仍需要这些二进制。

四、事件枚举：理解"谁在哪发射什么"

索引 Enumerations 分节的核心价值是给出所有可订阅事件的权威名单：

• PageEvent：page 实例可发射的全部事件（frame 生命周期、request 系列、dialog、console、filechooser 等）；
• BrowserEvent：browser 实例可发射的事件；
• BrowserContextEvent：browser context 的事件；
• LocatorEvent：locator 实例可发射的事件；
• WebWorkerEvent：worker 相关事件；
• AutofillAddressField：受支持的 autofill 地址字段名；
• InterceptResolutionAction 与 TargetType。

与事件枚举配套的是各 *Events 接口（描述回调收到的对象类型），如 PageEvents（文档注明：各事件的触发时机详见 PageEvent）、BrowserEvents、BrowserContextEvents、CDPSessionEvents、FrameEvents、LocatorEvents、WebWorkerEvents，以及唯一的 Namespaces 条目 CDPSessionEvent（CDPSession 发射的事件映射）。

五、Locator：带自动重试的定位器

Locator 描述"定位对象并对其执行操作"的策略：当操作因对象尚未就绪而失败时，整个操作会自动重试，各种前置条件（可见性、启用状态、稳定边界框等）由框架自动检查。可配置的重试维度由 Locator 上的 setTimeout、setVisibility、setEnsureElementIsInTheViewport、setWaitForEnabled、setWaitForStableBoundingBox 等方法表达，选项接口见 LocatorClickOptions、LocatorFillOptions、LocatorScrollOptions；AwaitedLocator 则描述 await locator 后拿到的类型。

六、选项接口：调用参数的类型契约

Interfaces 分节是索引中体量最大的一节，可按用途分组理解：

启动与连接：LaunchOptions（"可在启动任何浏览器时传递的通用启动选项"）、ConnectOptions（启动或连接已有实例时通用的浏览器选项）、Configuration（定义 Puppeteer 安装期与运行期的配置行为，各属性见具体字段）、ChromeSettings/ChromeHeadlessShellSettings/FirefoxSettings、ChromeReleaseChannel 相关的通道选择、CommandOptions。

页面操作：GoToOptions、ReloadOptions、SetContentWaitForOptions、QueryOptions、WaitForOptions、WaitForSelectorOptions、WaitForTargetOptions、WaitForNetworkIdleOptions、WaitTimeoutOptions、FrameWaitForFunctionOptions、FrameAddScriptTagOptions/FrameAddStyleTagOptions、CreatePageOptions。

动作与输入：ActionOptions、ClickOptions、MouseClickOptions/MouseMoveOptions/MouseWheelOptions/MouseOptions、KeyboardTypeOptions/KeyDownOptions/KeyPressOptions、Moveable、ActionResult。

坐标与几何：BoundingBox、BoxModel、Point、Quad、Offset、ScreenshotClip。

截图与 PDF：ScreenshotOptions、ElementScreenshotOptions、ImageFormat、VideoFormat、PDFOptions（"配置 Page.pdf() 生成 PDF 的合法选项"）、PDFMargin、PaperFormat。其中索引内联给出了各纸张格式的精确尺寸，做 PDF 生成时应直接引用：

格式	尺寸（英寸）	尺寸（厘米）
Letter	8.5 x 11 in	21.59 x 27.94 cm
Legal	8.5 x 14 in	21.59 x 35.56 cm
Tabloid	11 x 17 in	27.94 x 43.18 cm
Ledger	17 x 11 in	43.18 x 27.94 cm
A0	33.1102 x 46.811 in	84.1 x 118.9 cm
A1	23.3858 x 33.1102 in	59.4 x 84.1 cm
A2	16.5354 x 23.3858 in	42 x 59.4 cm
A3	11.6929 x 16.5354 in	29.7 x 42 cm
A4	8.2677 x 11.6929 in	21 x 29.7 cm
A5	5.8268 x 8.2677 in	14.8 x 21 cm
A6	4.1339 x 5.8268 in	10.5 x 14.8 cm

Cookie 体系：Cookie（cookie 对象）、CookieParam（页面级 cookies API 的写入参数）、CookieData（浏览器级 cookies API 的写入参数）、DeleteCookiesRequest、CookiePartitionKey（Chrome 的 cookie 分区键）、CookiePriority（对应 IETF cookie-priority 草案）、CookieSameSite_2、CookieSourceScheme。

网络模拟与请求改写：NetworkConditions、InternalNetworkConditions、ContinueRequestOverrides（request.continue() 的覆盖项）、ResponseForRequest（request.respond() 所需响应数据）、RemoteAddress。

PWA 与扩展：InstallPWAOptions/UninstallPWAOptions/LaunchPWAOptions/GetPWAStateOptions（分别对应 Browser.installPWA()/uninstallPWA()/launchPWA()/getPWAState()）、PWAState（已安装 Web 应用的 OS 集成状态）、PWADisplayMode（用户偏好在独立窗口还是浏览器标签中打开）、ExtensionInstallOptions。

多屏与其他：AddScreenParams、ScreenInfo、ScreenOrientation_2、WindowBounds、WorkAreaInsets、WindowState；DownloadBehavior、GeolocationOptions、MediaFeature、Metrics、HeapSnapshotOptions（Page.captureHeapSnapshot() 选项）、TracingOptions、SnapshotOptions、BrowserContextOptions（含下载策略 DownloadPolicy）、PermissionDescriptor_2/PermissionState_2、Credentials、Issue（DevTools issue 表示）、NewDocumentScriptEvaluation、SerializedAXNode、SupportedWebDriverCapabilities（"Puppeteer 自身不设置的 WebDriver BiDi 能力"）、CustomQueryHandler（自定义查询处理器的结构）、Viewport、Device。

七、Variables 与 Type Aliases：常量、联合类型与工具类型

Variables 分节列出的常量直接决定了模拟与按键能力：

• KnownDevices：设备清单，供 Page.emulate() 使用（如模拟 iPhone、Pixel 的视口与 UA 组合）；
• PredefinedNetworkConditions：预定义网络条件清单，供 Page.emulateNetworkConditions() 使用（如 offline、Slow 3G、Fast 4G）；
• MouseButton：合法鼠标按钮的枚举（"left"/"right"/"middle" 等）；
• DEBUG_PREFIXES（实验性）：调试日志通道前缀；
• DEFAULT_INTERCEPT_RESOLUTION_PRIORITY：协作式请求拦截的默认裁决优先级；
• asyncDisposeSymbol / disposeSymbol：支持 using/await using 语法的资源释放符号（Page、Browser、JSHandle 等均声明了对应的 _disposeSymbol_/_asyncDisposeSymbol_ 方法）；
• puppeteer：默认导出实例本身。

Type Aliases 分节值得单独梳理，因为它们约束了你能写什么函数、传什么值：

• 按键与输入：KeyInput 是"所有可传给接受用户输入的函数（如 keyboard.press）的合法按键"的联合类型。
• 求值语义：EvaluateFunc 与 EvaluateFuncWith 描述 evaluate 系列方法的函数形态；Awaitable/AwaitableIterable/AwaitablePredicate/Predicate 描述可等待的返回值与谓词；Handler/EventType/EventsWithWildcard 是事件系统的类型基础。
• 句柄推导：HandleFor/NodeFor/ElementFor/FlattenHandle/HandleOr 让 evaluateHandle 的返回类型自动随输入句柄推导。
• 协议与生命周期：ProtocolType、ProtocolLifeCycleEvent、PuppeteerLifeCycleEvent、CDPEvents、ResourceType（渲染引擎视角的 HTTP 请求资源类型）、ErrorCode。
• 调试与实验：DebugPrefix（实验性）、ExperimentsConfiguration（"定义 Puppeteer 的实验选项"）、SupportedBrowser（"Puppeteer 支持的浏览器"）。
• 已弃用项：Permission 被标记为 Deprecated。
• 其他：Mapper、InnerParams、LowerCasePaperFormat、AdapterState（模拟的蓝牙适配器状态）、AutofillData、PreconnectedPeripheral、TargetFilterCallback、VisibilityOption（等待元素 visible 还是 hidden，null 关闭可见性检查）、WindowId、TargetType 对应的 TargetFilterCallback。

八、从索引回到源码：验证 API 面的三条路径

1. 类型导出路径：packages/puppeteer-core/src/api/ 目录（api.ts）是 Classes 分节的主要来源；packages/puppeteer-core/src/common/ 承载 Cookie、EventEmitter、Viewport、Errors 等横切实现；packages/puppeteer-core/src/cdp/ 提供 CDP 专属能力（Accessibility、Coverage、Tracing、WebMCP 等，见 Page.ts 顶部的导入清单）。
2. Node 入口路径：packages/puppeteer 是"带浏览器下载能力"的发行包，puppeteer.ts 导出单例，getConfiguration.ts 负责读取 puppeteer.config.js/环境变量（本仓库根目录即含 puppeteer.config.js 作为真实示例）。
3. 文档页面路径：索引中每个符号都有独立的 docs/api/puppeteer.*.md 页面（如 puppeteer.page.md、puppeteer.browser.md），提供方法级签名、参数与示例；配套的 browsers-api 文档 则覆盖 @puppeteer/browsers 子包的符号。

九、阅读路径建议

• 首次上手：puppeteer（默认导出）→ PuppeteerNode.launch() → Browser → BrowserContext → Page → Frame/ElementHandle，这条链覆盖 90% 的日常自动化；
• 网络控制：HTTPRequest/HTTPResponse + request/requestfinished/requestfailed 三事件 + ContinueRequestOverrides/ResponseForRequest；
• 稳定性工程：Locator + 各 WaitFor*Options + TimeoutError；
• 高级能力：CDPSession（直通协议）、Accessibility（无障樹）、Coverage/Tracing（性能与覆盖率）、实验性的 Extension/WebMCP/BluetoothEmulation。

按这条索引阅读顺序，你可以仅凭 docs/api/ 目录加上述源码路径，独立完成从启动浏览器到深入协议层的任意 Puppeteer 开发任务。