企业官网建设流程全解析

Puppeteer Browser.getPWAState()：读取已安装 PWA 的 OS 集成状态（徽章计数与文件处理器）

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer

本篇指南聚焦 Puppeteer 的Browser.getPWAState()方法：它用于查询一个已安装渐进式 Web 应用（PWA）在操作系统层面的集成状态，包括应用图标上的当前徽章计数（badge count）与应用向 OS 注册的文件处理器（file handlers）。读完本文，你将掌握该方法的签名、参数与返回值结构、"仅限管道（pipe）连接"的使用约束，以及它在installPWA/launchPWA/uninstallPWA这套 PWA 生命周期 API 中的位置，并能直接写出可运行的状态查询与验证代码。

方法定位：PWA 生命周期 API 之一

Browser.getPWAState()是 PuppeteerBrowser类上的抽象方法，定义在 api/Browser.ts：

class Browser { abstract getPWAState(options: GetPWAStateOptions): Promise<PWAState>; }

它的职责是：返回一个已安装 PWA 的 OS 集成状态，例如徽章计数和已注册的文件处理器。从源码结构看，它与另外三个 PWA 方法共同构成一组围绕"manifest id"的应用生命周期 API（见 api/Browser.ts）：

其中installPWA会返回 manifest id，可直接传给getPWAState、launchPWA或uninstallPWA，因此getPWAState的典型输入正是安装时拿到的 id。

参数：GetPWAStateOptions

参数options的类型为 GetPWAStateOptions，完整定义见 api/Browser.ts：

export interface GetPWAStateOptions { /** * The id from the web app's manifest file. */ manifestId: string; }

关于manifestId的取值，源码中InstallPWAOptions.manifestId的注释给出了更具体的说明（见 api/Browser.ts）："The id from the web app's manifest file, commonly the URL of the site installing the web app."——即 manifest 文件中的 id，常见形态就是安装该 Web 应用的站点 URL。实际开发中最可靠的做法是：先调用installPWA，把它的返回值作为manifestId传递下去。

返回值：PWAState

方法返回Promise<PWAState>，PWAState 接口定义见 api/Browser.ts：

export interface PWAState { /** * The current badge count shown on the app icon. */ badgeCount: number; /** * The file handlers registered by the app with the OS. */ fileHandlers: Protocol.PWA.FileHandler[]; }

两个字段对应的是 Chromium 侧"应用已安装到桌面/OS 后"的集成数据：badgeCount反映未读数类标记，fileHandlers反映 manifest 中声明、并由浏览器登记到系统的文件类型处理项。fileHandlers的元素类型直接复用 CDP 协议定义Protocol.PWA.FileHandler，因此其具体字段随 Chromium 协议版本演进。

使用约束：三条硬性限制

官方文档（见 docs/api/puppeteer.browser.getpwastate.md）的 Remarks 与源码共同划定了三条边界：

1. 仅在管道连接下可用。Puppeteer 默认通过 WebSocket 连接浏览器；PWA 相关的 CDP 域（PWA）只在 pipe 连接下提供。要在本地启动时启用 pipe，需在启动选项中显式设置，见 node/LaunchOptions.ts 中pipe选项的说明："Connect to a browser over a pipe instead of a WebSocket."。
2. 只对已安装的应用有意义。文档明确注明："Meaningful only for an app that is currently installed; querying an unknown manifest id rejects." 即查询一个未安装（或已卸载）应用的 manifest id 时，Promise 会 reject。
3. 配置了网络限制时直接抛错。CDP 实现里对每个 PWA 方法都有同一个前置检查（见 cdp/Browser.ts）：若浏览器配置了网络限制，调用会抛出'PWA APIs are not supported when network restrictions are configured.'。这一点有测试用例直接验证：network_restrictions.test.ts 中 "PWA validation" 一节断言installPWA、launchPWA、uninstallPWA、getPWAState在该场景下均抛出同一错误信息。

源码级实现：一次 CDP 命令的透传

CDP 实现位于 cdp/Browser.ts，逻辑非常直接：

override async getPWAState(options: GetPWAStateOptions): Promise<PWAState> { if (this.#hasNetworkRestrictions) { throw new Error( 'PWA APIs are not supported when network restrictions are configured.', ); } const {badgeCount, fileHandlers} = await this.#connection.send( 'PWA.getOsAppState', {manifestId: options.manifestId}, ); return {badgeCount, fileHandlers}; }

可以读出三点实现事实：

• 方法在浏览器级 CDP 会话（this.#connection）上直接发送PWA.getOsAppState，不依赖任何页面或目标，这与installPWA发送PWA.install、launchPWA发送PWA.launch的模式一致（见 cdp/Browser.ts）；
• 协议返回的badgeCount、fileHandlers字段被原样解构并组装成PWAState返回，无额外变换；
• 网络限制检查发生在协议调用之前，属于快速失败。

与launchPWA相比，getPWAState的实现没有任何 target 解析逻辑（launchPWA需要把PWA.launch返回的 tab target 解析为其子 page target），因此它是这组 API 中调用路径最短、也最适合作为"安装后断言"使用的方法。

实战：安装、查询、启动、卸载的完整链路

下面的示例把getPWAState放进完整的 PWA 生命周期中，流程与仓库集成测试 pwa.test.ts 保持一致。注意pwa.test.ts开头注明：The PWA CDP domain is only available over a pipe connection。

import puppeteer from 'puppeteer'; // 必须用 pipe 连接启动，PWA 域才可用 const browser = await puppeteer.launch({pipe: true}); const manifestId = 'https://example.com/'; // 与 manifest 中的 id 一致 // 1. 安装（installPWA 返回 manifestId，可传递给后续所有 PWA 方法） await browser.installPWA({ manifestId, installUrlOrBundleUrl: 'https://example.com/', displayMode: 'standalone', // 可选：'standalone' | 'browser' }); // 2. 查询 OS 集成状态 const state = await browser.getPWAState({manifestId}); console.log(state.badgeCount); // 应用图标上的徽章计数 console.log(state.fileHandlers); // 应用向 OS 注册的文件处理器 // 3. 启动应用，拿到其 Page const page = await browser.launchPWA({manifestId}); console.log(await page.title()); await page.close(); // 4. 卸载后，查询将 reject await browser.uninstallPWA({manifestId}); await expect(browser.getPWAState({manifestId})).rejects.toThrow();

测试 pwa.test.ts 中 "installs and uninstalls a PWA" 用例正是这条链路的自动化验证：安装后getPWAState能 resolve 出已安装应用的状态；uninstallPWA之后再次调用getPWAState则rejects.toThrow()，印证了"未知 manifest id 会 reject"的文档约定。

相关 API 文档

• Browser.installPWA()：安装应用并获取 manifest id（getPWAState的推荐前置步骤）
• Browser.launchPWA()：启动已安装应用并取得其页面
• Browser.uninstallPWA()：卸载应用
• GetPWAStateOptions：参数接口
• PWAState：返回值接口

小结

Browser.getPWAState({manifestId})是 Puppeteer PWA 工具链中的"状态断言"入口：一次PWA.getOsAppStateCDP 调用即可拿到已安装应用的badgeCount与fileHandlers。使用时记住三件事——启动时开启pipe: true、manifest id 必须来自真实安装的应用（未安装即 reject）、浏览器配置网络限制时整组 PWA API 都会抛错。结合installPWA的返回值串联起安装—查询—启动—卸载的完整链路，就能对 PWA 的桌面集成行为做端到端的自动化验证。

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer