跳转到内容

安装中的概念

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 属性,不代表当前页面一定会收到事件。

排查时记录以下信息:

  1. 浏览器版本、操作系统,以及应用是否已在当前配置文件中安装。
  2. 在 Application › Manifest 中修复解析或图标加载错误。检查 manifest 最终响应及其 HTTP 状态;JSON 格式的错误响应并不是有效的应用 manifest。
  3. 检查菜单里的安装操作,记录入口缺失、添加快捷方式或安装应用的实际结果。
  4. 单独测试 beforeinstallprompt 监听器。只有收到并保存真实事件后,才启用调用 prompt() 的按钮。参见安装提示示例。
  5. 单独测试离线导航。存在 navigator.serviceWorker 仅说明支持该 API,不代表已注册 worker、当前页面受到控制,或已缓存可用响应。

Chrome 的当前公开清单列出参与度、HTTPS 和 manifest 条件,没有把 service worker 列为要求。较早的变更公告描述了当时安装提示的 fetch 处理器检查。不能把那条历史说明当成所有当前浏览器版本的通用要求。

示例提供常见的 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" 也能通过检查,但两种场景会渲染同一张位图。

规范

规范状态
无。