# pwa-install 0.7.0 加入 Web Install API 支持

> pwa-install 组件的 0.7.0 发布说明列出了面向 Chromium 155+ 的 Web Install API 支持、应用内浏览器识别、Apple 引导流程与泰语语言包。

`khmyznikov/pwa-install` 项目于 2026-09-14 发布了 v0.7.0，而在它自己的 Highlights 标题下，
第一条就是面向 Chromium 155 及更高版本的 Web Install API 支持，并带有到
`beforeinstallprompt` 的安全回退。于是在这个开箱即用的安装对话框里，第二条基于 promise 的安装
入口与开发者此前一直对接的那条基于事件的入口同时存在
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

说明的其余部分涉及应用内浏览器识别、面向 Apple 与 Android 设备的引导式安装流程、分浏览器的安装
说明、Android 回退检测，以及构建改动。下面按组逐条列出这些改动，用的是发布说明与 Web Install API
解释文档本身的措辞
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

## 这份发布说明列了什么

说明自己分了三个标题：Highlights、Browser Compatibility and Fixes，以及 Events and Developer
Experience。它还记录了一位新贡献者 @joeblew999，并把其首次贡献归于 pull request 170，另外给出了
一个对比 v0.6.4 与 v0.7.0 的完整 changelog 链接
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

### Web Install API 入口

Highlights 的第一条写明，这次发布加入了面向 Chromium 155+ 的 Web Install API 支持，包括
`manifest-id`、当前文档安装与跨应用安装、更好的可用性检测、详细的失败上报，以及到
`beforeinstallprompt` 的安全回退，并把它归于 pull request 168。解释文档把两种调用形态定义为
`navigator.install()` 与 `navigator.install({ manifest, manifestId })`；字典形式支持跨应用安装
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

Events and Developer Experience 这一组让这条双路径从应用代码里可被观察。说明写明，这次发布加入了
`pwa-install-backend-event`，用来报告这次安装使用的是 Web Install API 还是
`beforeinstallprompt`，并包含回退原因；同时暴露了 `isWebInstallSupported`，并把安装失败事件的
细节扩展为带有后端、错误与回退信息
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

### 应用内浏览器与 Apple 设备

Highlights 的第二条与第三条讲的是那些安装流程本身就是一串操作指引的场景。说明写明，这次发布加入了
应用内浏览器识别，以及面向 Apple 与 Android 设备的引导式安装流程，其中包括复制或在 Safari 中打开
应用链接，并更新了演示页的覆盖；还写明它加入了对 iOS、iPadOS 与 macOS 27+ 的原生观感兼容，并更新了
Aqua 风格样式、模糊效果、图标与安装说明。第四条加入了泰语 `th` 语言包，归于 pull request 170
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

在 Browser Compatibility and Fixes 下，说明写明这次发布为 Yandex Browser、Microsoft Edge、
Opera 以及 Apple 设备上的 Firefox 新增并细化了安装说明；修复了不支持 Service Worker 的 iOS
webview 被错误判定为非 Apple 浏览器的问题，并引用了 issue 161；修复了 Apple 移动端对话框在横屏下的
布局；并改进了原生安装提示不可用时的 Android 回退检测
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

最后这两条正是这类组件证明自身价值的地方，因为按浏览器划分的差异是有文档记录的。MDN 写明，在
Android 上，唯一会把 PWA 以 WebAPK 方式安装的浏览器是带 Google Mobile Services 的设备上的
Chrome 以及三星设备上的 Samsung Internet，而 Firefox、Edge、Opera 以及其他浏览器加上的是一个带
浏览器徽标的主屏快捷方式。在 Apple 平台上它写明，在 iOS 16.3 及更早版本上，PWA 只能用 Safari
安装；而在 iOS 16.4 及更高版本上，可以从 Safari、Chrome、Edge、Firefox 与 Orion 的分享菜单安装
([MDN，Making PWAs installable](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable))。

### 事件、声明文件与构建改动

Developer Experience 下剩下的条目属于打包而不是行为。说明写明，这次发布重构了安装逻辑，并改进了
生成的 TypeScript 声明与自定义元素元数据；加入了构建期类型检查与声明文件生成，把 TypeScript 的
转译切换到 esbuild，并显式以 ES2021 为目标；还刷新了依赖、生成的产物包、本地化词条、文档、截图、
演示 manifest 与 PWA 资源
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

## Web Install API 规定了什么

发布说明点名的这项特性由 Web Install API 解释文档规定，其状态一节把该文档记为 Active，预期归属
场所为 WebApps WG。该文档把 `navigator.install()` 定义为 JavaScript 入口点，并写明它同时定义了
每个入口点共用的安装算法，涵盖 manifest 的获取、解析与校验，用户激活、沙箱与跨源闸门，同意界面的
契约，以及返回给调用方的错误分类
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

发布说明提到的两种调用形态都出现在那里。该文档写明开发者调用
`navigator.install({ manifest: <url> [, manifestId: <url>] })`；写明只有当 `manifest` 处的
JSON 含有 `id` 时，开发者才可以省略 `manifestId`；并写明整个字典对象也可以完全省略，此时安装目标
就是当前已加载页面的 manifest。在它的目标里写明，该 API 扩展了 `beforeinstallprompt` 的功能，而
后者无法安装除当前已加载的 Web 应用之外的内容
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

该文档的错误清单，正是发布说明里"详细的失败上报"背后的细节。它写明，如果安装完成，promise 会
resolve；而拒绝时会给出一个 `DOMException`：用户中止安装流程时为 `AbortError`；所提供的数据有
问题时为 `DataError`，其中列举了无效的 `manifest` URL、manifest 获取失败、manifest 文件格式错误、
在 manifest 未声明 `id` 时省略了 `manifestId`，以及提供的 `manifestId` 与浏览器计算出的那个不
匹配。它的步骤清单还写明，没有瞬时用户激活的调用会以 `NotAllowedError` 被拒绝，而沙箱化的框架或
跨源子框架会以 `InvalidStateError` 被拒绝
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

这些条件里有一条还附了一个量化代价。该文档写明，按照 manifest 规范，如果没有 `id` 成员，计算出的
字符串会解析为 `start_url` 的值；它并写明截至 2024 年，只有大约 4% 的 Web 应用在其 manifest 里
定义了 `id`。它还写明，对于没有定义 `id` 字段的应用，API 调用方必须带上预期的计算 id，而这个计算
id 可以在基于 Chromium 的浏览器开发者工具的 Application 面板里看到
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

## 对 PWA 开发者为什么重要

实际后果是，一个安装按钮现在有两种可能的后端，各自有不同的失败语义，而发布说明里的
`pwa-install-backend-event` 存在的意义就是说出究竟跑了哪一条。MDN 把较早那条路径描述为事件驱动且
没有时间保证：`beforeinstallprompt` 事件在浏览器检测到某个网站可以作为渐进式 Web 应用安装时触发；
它的触发时间没有保证，尽管通常发生在页面加载时。
于是一个建立在该事件上的页内安装按钮，其可用性不会超过该事件本身
([MDN，beforeinstallprompt 事件](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeinstallprompt_event))。

基于 promise 的路径把这个关系倒了过来，这也是为什么该解释文档的那些闸门比它的顺利路径更要紧。它
写明，没有瞬时用户激活的调用会以 `NotAllowedError` 被拒绝，并且始终需要用户同意，同时把静默或无人
值守的安装列在非目标里。一个接到 `navigator.install()` 的按钮可以在开发者选择的时机被调用，而不是
在事件到来时，但前提是必须来自一次真实的用户手势，并且所在框架既不是沙箱化的，也不是跨源子框架
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

manifest `id` 这项要求是最可能让既有代码库意外的部分。该文档写明，只有当 manifest 自身含有 `id`
时才允许省略 `manifestId`；而所提供的 `manifestId` 与浏览器计算出的 id 不匹配时会以 `DataError`
被拒绝。它还写明，截至 2024 年只有大约 4% 的 Web 应用在其 manifest 里定义了 `id`，而对于没有定义
`id` 的应用，API 调用方必须带上预期的计算 id
([Web Install API 解释文档](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md))。

在 iOS 上，MDN 写明 `beforeinstallprompt` 这套做法不被支持，并列出那里的安装路径是 iOS 16.3 及
更早版本上的 Safari，或 iOS 16.4 及更高版本上若干浏览器的分享菜单
([MDN，Making PWAs installable](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable))。
发布说明在改动中列出了面向 Apple 设备的引导式安装流程，以及细化后的分浏览器安装说明
([v0.7.0 发布说明](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0))。

## 站内相关条目

- [Workbox](/zh/reference/service-worker/workbox/)：可沿这条交叉链接单独了解 service worker 构建工具。
- [Service worker 调试](/zh/reference/service-worker/debugging/)：这次发布修复了不支持 Service
  Worker 的 iOS webview 被判定为非 Apple 浏览器的问题，而解释文档写明 manifest 的计算 id 可以在
  Chromium 开发者工具的 Application 面板里读到；可以把这条交叉链接与这两点放在一起看。
- [Lighthouse 与已移除的 PWA 类别](/zh/reference/performance/lighthouse/)：可沿这条交叉链接单独
  了解 PWA 审计。

## 待核实与存疑之处

- Chromium 155 是否默认启用 Web Install API，尚未确认。
- 这次发布实现的 API 版本是否与解释文档当前的 `navigator.install()` 签名一致，包括发布说明里写作
  `manifest-id` 的那个 `manifestId` 成员，尚未确认。
- `pwa-install-backend-event` 所携带的回退原因有哪些取值、以及它们是否在任何地方被枚举，
  尚未确认。
- 原生观感那一条里的 "macOS 27+" 是只限定 macOS，还是也限定与之并列的 iOS 与 iPadOS 版本，
  尚未确认。
- 被记为 issue 161 的 Service Worker 检测缺陷涉及哪些 iOS 或 webview 版本，以及横屏布局修复覆盖
  哪些 Apple 设备尺寸，都尚未确认。
- 在组件回退为操作指引的那些平台上，Web Install API 的同意界面是否会出现，尚未确认。

## 参考来源

- [pwa-install v0.7.0](https://github.com/khmyznikov/pwa-install/releases/tag/v0.7.0)（github.com）
- [Web Install API explainer](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/WebInstall/explainer.md)（github.com）
- [Window: beforeinstallprompt event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeinstallprompt_event)（developer.mozilla.org）
- [Making PWAs installable](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)（developer.mozilla.org）