Puppeteer API Reference 指南核心类、入口函数与类型系统的完整导读【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerAPI Reference 索引文档是 PuppeteerJavaScript API for Chrome and FirefoxTypeScript 公共 API 面的总目录它把puppeteer命名空间下所有可导出的类、枚举、函数、接口、变量与类型别名按符号分类罗列并给出每个符号的一句话职责说明。读完本文你可以建立一张符号 → 职责 → 源码位置的地图知道在写自动化、做网络拦截、处理事件或生成 PDF/截图时该查阅哪个类型以及如何对照仓库源码验证这些 API 的真实实现。一、Reference 的整体结构七类符号如何组织索引文档按 TypeScript API 报告的标准分节组织共七类符号分节内容数量级Classes可实例化/可扩展的运行时对象如Browser、Page、ElementHandle40Enumerations事件名与取值集合如PageEvent、BrowserEvent8Functions顶层入口函数如launch(options)、connect(options)4Interfaces选项与数据结构接口如LaunchOptions、ClickOptions、Viewport100Namespaces事件映射命名空间如CDPSessionEvent1Variables常量与单例如KnownDevices、PredefinedNetworkConditions、puppeteer9Type Aliases工具类型与取值联合如Awaitable、KeyInput、PaperFormat70这一结构与仓库源码的组织方式一一对应packages/puppeteer-core/src/api/下的 api.ts 桶文件 集中再导出Browser、BrowserContext、CDPSession、Dialog、ElementHandle、Frame、HTTPRequest、HTTPResponse、InputKeyboard/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、WebWorkerBrowser代表一个浏览器实例来源于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 Workerworkercreated/workerdestroyed事件在 page 对象上发射以标记 worker 生命周期。BrowserLauncher描述能创建并启动浏览器实例的类。从源码看PuppeteerNode.ts 的#getLauncher()会在chrome与firefox之间选择ChromeLauncher或FirefoxLauncher这正是接口在实现层的落点。2.2 页面与 DOMPage、Frame、ElementHandle、JSHandle、RealmPage与浏览器中单个标签页或扩展后台页交互的核心类一个 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 下支持泛型ElementHandleHTMLSelectElement以获得更精确的类型检查。JSHandle代表对 JavaScript 对象的引用可由Page.evaluateHandle()创建同样阻止被引用对象被 GC且可用作各类求值函数的参数并解析为被引用对象。Realm从源码结构看Page同时持有 CDP 与 BiDi 两套实现路径Realm是其中对可执行 JS 的隔离环境的抽象Page.ts 的导入清单即可印证其核心地位。2.3 输入模拟Keyboard、Mouse、TouchscreenKeyboard虚拟键盘 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、SecurityDetailsHTTPRequest代表页面发出的 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 自定义错误继承自PuppeteerErrorTimeoutError在page.waitForSelector、puppeteer.launch等操作因超时终止时抛出UnsupportedOperation在当前协议不支持某方法时抛出例如在 BiDi 协议下调用 CDP 专属能力。2.6 事件与交互对象EventEmitter、Dialog、FileChooser、DeviceRequestPrompt、ConsoleMessageEventEmitter多数 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、ScreenRecorderAccessibility提供检查浏览器无障碍树的方法。文档的备注信息量很大无障碍树是高度平台相关的BlinkChrome 渲染引擎有accessibility tree概念再翻译成各平台特定 APIPuppeteer 默认会近似模拟这一过滤过程只暴露有意思的节点。Coverage采集页面实际使用到的 JS/CSS 部分报告条目为 CoverageEntryJSCoverage 与 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 分节的核心价值是给出所有可订阅事件的权威名单PageEventpage 实例可发射的全部事件frame 生命周期、request 系列、dialog、console、filechooser 等BrowserEventbrowser 实例可发射的事件BrowserContextEventbrowser context 的事件LocatorEventlocator 实例可发射的事件WebWorkerEventworker 相关事件AutofillAddressField受支持的 autofill 地址字段名InterceptResolutionAction与TargetType。与事件枚举配套的是各*Events接口描述回调收到的对象类型如 PageEvents文档注明各事件的触发时机详见 PageEvent、BrowserEvents、BrowserContextEvents、CDPSessionEvents、FrameEvents、LocatorEvents、WebWorkerEvents以及唯一的 Namespaces 条目CDPSessionEventCDPSession发射的事件映射。五、Locator带自动重试的定位器Locator描述定位对象并对其执行操作的策略当操作因对象尚未就绪而失败时整个操作会自动重试各种前置条件可见性、启用状态、稳定边界框等由框架自动检查。可配置的重试维度由 Locator 上的setTimeout、setVisibility、setEnsureElementIsInTheViewport、setWaitForEnabled、setWaitForStableBoundingBox等方法表达选项接口见 LocatorClickOptions、LocatorFillOptions、LocatorScrollOptionsAwaitedLocator 则描述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。截图与 PDFScreenshotOptions、ElementScreenshotOptions、ImageFormat、VideoFormat、PDFOptions配置Page.pdf()生成 PDF 的合法选项、PDFMargin、PaperFormat。其中索引内联给出了各纸张格式的精确尺寸做 PDF 生成时应直接引用格式尺寸英寸尺寸厘米Letter8.5 x 11 in21.59 x 27.94 cmLegal8.5 x 14 in21.59 x 35.56 cmTabloid11 x 17 in27.94 x 43.18 cmLedger17 x 11 in43.18 x 27.94 cmA033.1102 x 46.811 in84.1 x 118.9 cmA123.3858 x 33.1102 in59.4 x 84.1 cmA216.5354 x 23.3858 in42 x 59.4 cmA311.6929 x 16.5354 in29.7 x 42 cmA48.2677 x 11.6929 in21 x 29.7 cmA55.8268 x 8.2677 in14.8 x 21 cmA64.1339 x 5.8268 in10.5 x 14.8 cmCookie 体系Cookiecookie 对象、CookieParam页面级 cookies API 的写入参数、CookieData浏览器级 cookies API 的写入参数、DeleteCookiesRequest、CookiePartitionKeyChrome 的 cookie 分区键、CookiePriority对应 IETF cookie-priority 草案、CookieSameSite_2、CookieSourceScheme。网络模拟与请求改写NetworkConditions、InternalNetworkConditions、ContinueRequestOverridesrequest.continue()的覆盖项、ResponseForRequestrequest.respond()所需响应数据、RemoteAddress。PWA 与扩展InstallPWAOptions/UninstallPWAOptions/LaunchPWAOptions/GetPWAStateOptions分别对应Browser.installPWA()/uninstallPWA()/launchPWA()/getPWAState()、PWAState已安装 Web 应用的 OS 集成状态、PWADisplayMode用户偏好在独立窗口还是浏览器标签中打开、ExtensionInstallOptions。多屏与其他AddScreenParams、ScreenInfo、ScreenOrientation_2、WindowBounds、WorkAreaInsets、WindowStateDownloadBehavior、GeolocationOptions、MediaFeature、Metrics、HeapSnapshotOptionsPage.captureHeapSnapshot()选项、TracingOptions、SnapshotOptions、BrowserContextOptions含下载策略 DownloadPolicy、PermissionDescriptor_2/PermissionState_2、Credentials、IssueDevTools issue 表示、NewDocumentScriptEvaluation、SerializedAXNode、SupportedWebDriverCapabilitiesPuppeteer 自身不设置的 WebDriver BiDi 能力、CustomQueryHandler自定义查询处理器的结构、Viewport、Device。七、Variables 与 Type Aliases常量、联合类型与工具类型Variables 分节列出的常量直接决定了模拟与按键能力KnownDevices设备清单供Page.emulate()使用如模拟 iPhone、Pixel 的视口与 UA 组合PredefinedNetworkConditions预定义网络条件清单供Page.emulateNetworkConditions()使用如offline、Slow 3G、Fast 4GMouseButton合法鼠标按钮的枚举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 的实验选项、SupportedBrowserPuppeteer 支持的浏览器。已弃用项Permission 被标记为 Deprecated。其他Mapper、InnerParams、LowerCasePaperFormat、AdapterState模拟的蓝牙适配器状态、AutofillData、PreconnectedPeripheral、TargetFilterCallback、VisibilityOption等待元素 visible 还是 hiddennull关闭可见性检查、WindowId、TargetType 对应的 TargetFilterCallback。八、从索引回到源码验证 API 面的三条路径类型导出路径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 顶部的导入清单。Node 入口路径packages/puppeteer是带浏览器下载能力的发行包puppeteer.ts 导出单例getConfiguration.ts 负责读取puppeteer.config.js/环境变量本仓库根目录即含 puppeteer.config.js 作为真实示例。文档页面路径索引中每个符号都有独立的docs/api/puppeteer.*.md页面如 puppeteer.page.md、puppeteer.browser.md提供方法级签名、参数与示例配套的 browsers-api 文档 则覆盖puppeteer/browsers子包的符号。九、阅读路径建议首次上手puppeteer默认导出→PuppeteerNode.launch()→Browser→BrowserContext→Page→Frame/ElementHandle这条链覆盖 90% 的日常自动化网络控制HTTPRequest/HTTPResponserequest/requestfinished/requestfailed三事件 ContinueRequestOverrides/ResponseForRequest稳定性工程Locator 各WaitFor*OptionsTimeoutError高级能力CDPSession直通协议、Accessibility无障樹、Coverage/Tracing性能与覆盖率、实验性的Extension/WebMCP/BluetoothEmulation。按这条索引阅读顺序你可以仅凭docs/api/目录加上述源码路径独立完成从启动浏览器到深入协议层的任意 Puppeteer 开发任务。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puppeteer API Reference 指南：核心类、入口函数与类型系统的完整导读
Puppeteer API Reference 指南核心类、入口函数与类型系统的完整导读【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerAPI Reference 索引文档是 PuppeteerJavaScript API for Chrome and FirefoxTypeScript 公共 API 面的总目录它把puppeteer命名空间下所有可导出的类、枚举、函数、接口、变量与类型别名按符号分类罗列并给出每个符号的一句话职责说明。读完本文你可以建立一张符号 → 职责 → 源码位置的地图知道在写自动化、做网络拦截、处理事件或生成 PDF/截图时该查阅哪个类型以及如何对照仓库源码验证这些 API 的真实实现。一、Reference 的整体结构七类符号如何组织索引文档按 TypeScript API 报告的标准分节组织共七类符号分节内容数量级Classes可实例化/可扩展的运行时对象如Browser、Page、ElementHandle40Enumerations事件名与取值集合如PageEvent、BrowserEvent8Functions顶层入口函数如launch(options)、connect(options)4Interfaces选项与数据结构接口如LaunchOptions、ClickOptions、Viewport100Namespaces事件映射命名空间如CDPSessionEvent1Variables常量与单例如KnownDevices、PredefinedNetworkConditions、puppeteer9Type Aliases工具类型与取值联合如Awaitable、KeyInput、PaperFormat70这一结构与仓库源码的组织方式一一对应packages/puppeteer-core/src/api/下的 api.ts 桶文件 集中再导出Browser、BrowserContext、CDPSession、Dialog、ElementHandle、Frame、HTTPRequest、HTTPResponse、InputKeyboard/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、WebWorkerBrowser代表一个浏览器实例来源于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 Workerworkercreated/workerdestroyed事件在 page 对象上发射以标记 worker 生命周期。BrowserLauncher描述能创建并启动浏览器实例的类。从源码看PuppeteerNode.ts 的#getLauncher()会在chrome与firefox之间选择ChromeLauncher或FirefoxLauncher这正是接口在实现层的落点。2.2 页面与 DOMPage、Frame、ElementHandle、JSHandle、RealmPage与浏览器中单个标签页或扩展后台页交互的核心类一个 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 下支持泛型ElementHandleHTMLSelectElement以获得更精确的类型检查。JSHandle代表对 JavaScript 对象的引用可由Page.evaluateHandle()创建同样阻止被引用对象被 GC且可用作各类求值函数的参数并解析为被引用对象。Realm从源码结构看Page同时持有 CDP 与 BiDi 两套实现路径Realm是其中对可执行 JS 的隔离环境的抽象Page.ts 的导入清单即可印证其核心地位。2.3 输入模拟Keyboard、Mouse、TouchscreenKeyboard虚拟键盘 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、SecurityDetailsHTTPRequest代表页面发出的 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 自定义错误继承自PuppeteerErrorTimeoutError在page.waitForSelector、puppeteer.launch等操作因超时终止时抛出UnsupportedOperation在当前协议不支持某方法时抛出例如在 BiDi 协议下调用 CDP 专属能力。2.6 事件与交互对象EventEmitter、Dialog、FileChooser、DeviceRequestPrompt、ConsoleMessageEventEmitter多数 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、ScreenRecorderAccessibility提供检查浏览器无障碍树的方法。文档的备注信息量很大无障碍树是高度平台相关的BlinkChrome 渲染引擎有accessibility tree概念再翻译成各平台特定 APIPuppeteer 默认会近似模拟这一过滤过程只暴露有意思的节点。Coverage采集页面实际使用到的 JS/CSS 部分报告条目为 CoverageEntryJSCoverage 与 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 分节的核心价值是给出所有可订阅事件的权威名单PageEventpage 实例可发射的全部事件frame 生命周期、request 系列、dialog、console、filechooser 等BrowserEventbrowser 实例可发射的事件BrowserContextEventbrowser context 的事件LocatorEventlocator 实例可发射的事件WebWorkerEventworker 相关事件AutofillAddressField受支持的 autofill 地址字段名InterceptResolutionAction与TargetType。与事件枚举配套的是各*Events接口描述回调收到的对象类型如 PageEvents文档注明各事件的触发时机详见 PageEvent、BrowserEvents、BrowserContextEvents、CDPSessionEvents、FrameEvents、LocatorEvents、WebWorkerEvents以及唯一的 Namespaces 条目CDPSessionEventCDPSession发射的事件映射。五、Locator带自动重试的定位器Locator描述定位对象并对其执行操作的策略当操作因对象尚未就绪而失败时整个操作会自动重试各种前置条件可见性、启用状态、稳定边界框等由框架自动检查。可配置的重试维度由 Locator 上的setTimeout、setVisibility、setEnsureElementIsInTheViewport、setWaitForEnabled、setWaitForStableBoundingBox等方法表达选项接口见 LocatorClickOptions、LocatorFillOptions、LocatorScrollOptionsAwaitedLocator 则描述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。截图与 PDFScreenshotOptions、ElementScreenshotOptions、ImageFormat、VideoFormat、PDFOptions配置Page.pdf()生成 PDF 的合法选项、PDFMargin、PaperFormat。其中索引内联给出了各纸张格式的精确尺寸做 PDF 生成时应直接引用格式尺寸英寸尺寸厘米Letter8.5 x 11 in21.59 x 27.94 cmLegal8.5 x 14 in21.59 x 35.56 cmTabloid11 x 17 in27.94 x 43.18 cmLedger17 x 11 in43.18 x 27.94 cmA033.1102 x 46.811 in84.1 x 118.9 cmA123.3858 x 33.1102 in59.4 x 84.1 cmA216.5354 x 23.3858 in42 x 59.4 cmA311.6929 x 16.5354 in29.7 x 42 cmA48.2677 x 11.6929 in21 x 29.7 cmA55.8268 x 8.2677 in14.8 x 21 cmA64.1339 x 5.8268 in10.5 x 14.8 cmCookie 体系Cookiecookie 对象、CookieParam页面级 cookies API 的写入参数、CookieData浏览器级 cookies API 的写入参数、DeleteCookiesRequest、CookiePartitionKeyChrome 的 cookie 分区键、CookiePriority对应 IETF cookie-priority 草案、CookieSameSite_2、CookieSourceScheme。网络模拟与请求改写NetworkConditions、InternalNetworkConditions、ContinueRequestOverridesrequest.continue()的覆盖项、ResponseForRequestrequest.respond()所需响应数据、RemoteAddress。PWA 与扩展InstallPWAOptions/UninstallPWAOptions/LaunchPWAOptions/GetPWAStateOptions分别对应Browser.installPWA()/uninstallPWA()/launchPWA()/getPWAState()、PWAState已安装 Web 应用的 OS 集成状态、PWADisplayMode用户偏好在独立窗口还是浏览器标签中打开、ExtensionInstallOptions。多屏与其他AddScreenParams、ScreenInfo、ScreenOrientation_2、WindowBounds、WorkAreaInsets、WindowStateDownloadBehavior、GeolocationOptions、MediaFeature、Metrics、HeapSnapshotOptionsPage.captureHeapSnapshot()选项、TracingOptions、SnapshotOptions、BrowserContextOptions含下载策略 DownloadPolicy、PermissionDescriptor_2/PermissionState_2、Credentials、IssueDevTools issue 表示、NewDocumentScriptEvaluation、SerializedAXNode、SupportedWebDriverCapabilitiesPuppeteer 自身不设置的 WebDriver BiDi 能力、CustomQueryHandler自定义查询处理器的结构、Viewport、Device。七、Variables 与 Type Aliases常量、联合类型与工具类型Variables 分节列出的常量直接决定了模拟与按键能力KnownDevices设备清单供Page.emulate()使用如模拟 iPhone、Pixel 的视口与 UA 组合PredefinedNetworkConditions预定义网络条件清单供Page.emulateNetworkConditions()使用如offline、Slow 3G、Fast 4GMouseButton合法鼠标按钮的枚举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 的实验选项、SupportedBrowserPuppeteer 支持的浏览器。已弃用项Permission 被标记为 Deprecated。其他Mapper、InnerParams、LowerCasePaperFormat、AdapterState模拟的蓝牙适配器状态、AutofillData、PreconnectedPeripheral、TargetFilterCallback、VisibilityOption等待元素 visible 还是 hiddennull关闭可见性检查、WindowId、TargetType 对应的 TargetFilterCallback。八、从索引回到源码验证 API 面的三条路径类型导出路径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 顶部的导入清单。Node 入口路径packages/puppeteer是带浏览器下载能力的发行包puppeteer.ts 导出单例getConfiguration.ts 负责读取puppeteer.config.js/环境变量本仓库根目录即含 puppeteer.config.js 作为真实示例。文档页面路径索引中每个符号都有独立的docs/api/puppeteer.*.md页面如 puppeteer.page.md、puppeteer.browser.md提供方法级签名、参数与示例配套的 browsers-api 文档 则覆盖puppeteer/browsers子包的符号。九、阅读路径建议首次上手puppeteer默认导出→PuppeteerNode.launch()→Browser→BrowserContext→Page→Frame/ElementHandle这条链覆盖 90% 的日常自动化网络控制HTTPRequest/HTTPResponserequest/requestfinished/requestfailed三事件 ContinueRequestOverrides/ResponseForRequest稳定性工程Locator 各WaitFor*OptionsTimeoutError高级能力CDPSession直通协议、Accessibility无障樹、Coverage/Tracing性能与覆盖率、实验性的Extension/WebMCP/BluetoothEmulation。按这条索引阅读顺序你可以仅凭docs/api/目录加上述源码路径独立完成从启动浏览器到深入协议层的任意 Puppeteer 开发任务。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考