安装中的概念
PWA 可安装性条件:菜单安装与安装提示
发布于 更新于
可安装性条件是浏览器主动为页面提供安装入口(如地址栏图标或 beforeinstallprompt 事件)之前检查的一组条件;部分浏览器也允许用户在不满足这些条件时通过菜单手动安装。Chromium 浏览器(Chrome、Edge、Samsung Internet)要求安全源,外加带有名称、起始 URL、非 browser 显示模式与图标的 manifest;Chrome 和桌面 Edge 也允许用户手动安装没有 manifest 的页面,WebKit 称 iOS 26 上的 Safari 没有可安装性要求,Windows 上的 Firefox 143 把站点固定为任务栏 web 应用,同样没有记载 manifest 要求(BCD manifests.webapp、Chrome “Changes to the installability criteria”、WebKit Safari 26.0 发布文章、Firefox 143 发行说明)。
工作原理
链接到“工作原理”一节Chrome DevTools 的 Application › Manifest 面板中有一个 Installability 部分,描述安装错误,例如图标无法加载。检查项参照 Chrome 可安装性文章,但文章的排列顺序不同(尚未安装、用户参与度、HTTPS,然后是 manifest 成员):
- 页面来自安全上下文:
https:,或开发期间的http://localhost与http://127.0.0.1。 - 文档链接了一个可解析的 manifest(
<link rel="manifest">),其中包含name或short_name、start_url、取值为standalone、fullscreen或minimal-ui的display(或解析到其中之一的display_override),以及包含 192 px 与 512 px 条目的icons;安装对话框还要求至少一个 144 px 以上、PNG、SVG 或 WebP 格式、设置了sizes且purpose包含any的图标。 start_url位于scope内并返回一个文档(重定向到其他源会使检查失败)。prefer_related_applications不存在或为false。- 该应用尚未在当前浏览器配置文件中安装。
带 fetch 处理器的已注册 service worker 曾是清单的一部分,直到 Android 上的 Chrome 108 与桌面端的 Chrome 112 取消了从浏览器菜单安装时的这一要求;Chrome 为没有 service worker 的已安装应用提供默认离线页。那篇历史文章也描述了当时安装提示的 fetch 处理器检查;当前公开清单已不再列出这一项。Chrome 还会把事件(以及 Android 的 mini-infobar)推迟到参与度启发式满足之后,这就是 DevTools 面板报告“可安装”而事件不触发的原因。
其他浏览器采用不同的清单:
| 浏览器 | 提供安装之前要求什么 | 安装入口 |
|---|---|---|
| Edge(桌面端) | 与 Chrome 相同的 manifest 成员(MDN);Chrome 的版本门槛(Android 108、桌面 112)指的是 Chrome 版本 | 从浏览器菜单安装,有无 manifest 均可(MDN) |
| Samsung Internet | 与 Chrome 相同的 manifest 成员(MDN) | beforeinstallprompt(BCD 记录自 5.0 起) |
| Safari,iOS 与 iPadOS 26 | 无:从共享菜单添加的每个站点都以 web 应用打开,除非用户关闭 “Open as Web App” | 共享菜单 › “Add to Home Screen” |
| Safari,iOS 与 iPadOS 16.4 至 18 | 需要 manifest display: standalone 或 fullscreen(或旧的 apple-mobile-web-app-capable meta 标签)才进入 web 应用模式;否则为书签 |
共享菜单 › “Add to Home Screen” |
| Safari 17+,macOS 14+ | 无;File › “Add to Dock” 对任何页面可用,存在 manifest 时读取其取值 | File 菜单 |
| Firefox 143+,Windows | 未记载;发行说明描述了把网站作为 web 应用固定到任务栏,并说明该功能目前不适用于通过 Microsoft Store 安装的 Firefox | 发行说明未记载 |
| Firefox for Android | 一个 manifest;安装为主屏幕快捷方式,无事件 | 三点菜单 › “Install” |
通过 manifest 清单并不保证能在另一款浏览器安装。需要在目标浏览器和操作系统上测试实际安装路径。菜单安装与自动安装提示是不同的行为;没有收到事件,并不能证明菜单安装不可用。
页面可以检查自身控制的输入,并提供满足 Chromium 要求的 manifest。
检查应用,不把检查结果当成安装事件保证
链接到“检查应用,不把检查结果当成安装事件保证”一节先用 Chrome DevTools 检查 manifest,再分别测试浏览器菜单和页面内的安装按钮。短脚本无法重现浏览器的完整决定:用户参与度和此前是否安装也会影响安装提示。检测到 onbeforeinstallprompt 属性,不代表当前页面一定会收到事件。
排查时记录以下信息:
- 浏览器版本、操作系统,以及应用是否已在当前配置文件中安装。
- 在 Application › Manifest 中修复解析或图标加载错误。检查 manifest 最终响应及其 HTTP 状态;JSON 格式的错误响应并不是有效的应用 manifest。
- 检查菜单里的安装操作,记录入口缺失、添加快捷方式或安装应用的实际结果。
- 单独测试
beforeinstallprompt监听器。只有收到并保存真实事件后,才启用调用prompt()的按钮。参见安装提示示例。 - 单独测试离线导航。存在
navigator.serviceWorker仅说明支持该 API,不代表已注册 worker、当前页面受到控制,或已缓存可用响应。
Chrome 的当前公开清单列出参与度、HTTPS 和 manifest 条件,没有把 service worker 列为要求。较早的变更公告描述了当时安装提示的 fetch 处理器检查。不能把那条历史说明当成所有当前浏览器版本的通用要求。
用于开始测试的 manifest
链接到“用于开始测试的 manifest”一节示例提供常见的 Chromium 安装提示字段,是在真实站点上验证的起点,不保证跨浏览器安装成功。URL 与图标文件需要在站点上真实存在。
{ "name": "Field Notes", "short_name": "Notes", "id": "/notes/", "start_url": "/notes/?source=pwa", "scope": "/notes/", "display": "standalone", "background_color": "#ffffff", "theme_color": "#1f3a5f", "icons": [ { "src": "/notes/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" }, { "src": "/notes/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" }, { "src": "/notes/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" } ]}把 any 与 maskable 放在不同的图标条目中。Chrome 安装对话框需要 purpose 包含 any 的图标;写成单条 "purpose": "any maskable" 也能通过检查,但两种场景会渲染同一张位图。
另请参阅
链接到“另请参阅”一节- Changes to the installability criteria(developer.chrome.com)
- What does it take to be installable?(web.dev)
- WebKit features in Safari 26.0(webkit.org)
- beforeinstallprompt 事件
- iOS 添加到主屏幕
- 桌面端安装
iconsmanifest 成员- Firefox
规范
| 规范 | 状态 |
|---|---|
| 无。 | |