可安装性条件：PWA 如何才能被安装

一句话： 当 PWA 通过 HTTPS 提供服务、链接了包含最少必要字段和图标的 Web 应用清单时， 该 PWA 即为可安装状态——在 Chrome/Chromium 上，部分审计工具也会检查 Service Worker， 但在当前版本中，它不再是 beforeinstallprompt 的硬性门槛。

跨平台基础条件

大多数现代平台在一个简短的硬性要求列表上达成共识：

• HTTPS（开发环境可使用 localhost）。不安全的来源永远不符合条件。
• 已链接的 Web 应用清单，至少包含：
  • name 或 short_name
  • start_url
  • display 设为 standalone、fullscreen 或 minimal-ui（不能是 browser）
  • 至少一个 192 × 192 像素的图标和一个 512 × 512 像素的图标

满足这些条件，加上足够的用户参与度（在网站上花费的时间、重复访问） 以及应用尚未安装的状态，Chromium 才会触发 beforeinstallprompt，并启用浏览器的 环境安装 UI（mini-infobar、地址栏安装图标等）。

Service Worker 与离线质量： 强烈建议所有 PWA 注册 Service Worker——它支持离线访问、 后台同步、推送通知，并且 Lighthouse PWA 审计也要求注册 Service Worker。然而，根据当前 Chrome 版本，单独缺少 Service Worker 并不会阻止 beforeinstallprompt 事件触发。 三星 Internet 及部分其他 Chromium 浏览器可能仍会强制要求。请始终注册 Service Worker 以确保 PWA 体验质量。

Android（Chrome / Chromium）

Android 上的 Chrome 在触发 beforeinstallprompt 之前，除清单与 HTTPS 基础条件外， 还要求满足用户参与度启发式规则，且应用尚未安装。 即使清单条件已满足，Chrome 的启发式规则仍可能抑制 mini-infobar。 对已保存的 beforeinstallprompt 事件调用 prompt()，可以让你在明确的用户手势（例如 点击按钮）触发时显示安装对话框，而无需等待浏览器自动弹出 mini-infobar—— 但这并不绕过当初促使事件触发的参与度前提条件。 安装时，Chrome 会生成一个 WebAPK——一个轻薄的原生包装器—— 而非网页快捷方式。详见 WebAPK 参考文档。

iOS / Safari

Safari 评估一套不同的、更为有限的条件：

• 仍然需要 HTTPS。
• 链接的清单对 name、short_name、icons 和 display 有效，但旧版的 apple-touch-icon 和 apple-mobile-web-app-* meta 标签也会影响行为， 并在图标选择上优先于清单。
• 不存在 beforeinstallprompt 事件，也没有编程式安装 API。
• 安装手势完全是手动的：用户点击分享按钮，选择“添加到主屏幕”。
• 不需要 Service Worker，“添加到主屏幕”选项仍会出现，但离线功能仍需要它。
• iOS 创建的是网页剪辑（web clip），不是 WebAPK。推送通知、 徽标（Badging）及其他 API 的支持十分有限甚至不存在。 详见 iOS 添加到主屏幕。

桌面端（Windows、macOS、Linux、ChromeOS 上的 Chrome / Edge）

桌面 Chromium 浏览器应用相同的清单和 HTTPS 要求。安装 UI 为地址栏中的图标或 浏览器菜单下的“安装”菜单项；没有 mini-infobar 的等效物。 beforeinstallprompt 在桌面端也会触发，prompt() 的工作方式相同。 详见 桌面端安装。

三星 Internet 及其他 Android 浏览器

三星 Internet 应用自己的条件变体（HTTPS + 清单 + Service Worker）， 并显示自己的安装 UI。清单要求大体相同；图标集和命名期望可能略有不同。

Firefox

Android 版 Firefox（128+ 起）支持通过网站菜单中的“安装”操作来安装 PWA。 桌面版 Firefox 不支持 PWA 安装。

常见故障模式

症状	可能原因
beforeinstallprompt 从未触发	缺少 HTTPS、无效清单、display: browser，或（在部分浏览器上）缺少 Service Worker
Mini-infobar 被抑制	参与度启发式规则尚未满足；等待 beforeinstallprompt 触发后保存，再在合适时机从用户手势中调用 prompt()
主屏幕上缺少图标	图标尺寸错误；192 × 192 和 512 × 512 都是必需的
iOS 不显示“添加到主屏幕”	这不是失败——它始终出现在分享菜单中；只是无法用程序触发

兼容性

当前各浏览器的安装支持数据，请查看兼容性章节。

实践检查清单

• 网站通过 HTTPS 提供服务（或 localhost）。
• 清单通过 <link rel="manifest"> 链接在 <head> 中。
• 清单包含 name/short_name、start_url 以及 display: standalone（或 fullscreen/minimal-ui）。
• 清单包含 192 × 192 和 512 × 512 的图标（推荐 PNG；某些浏览器也接受带 purpose: any maskable 的 SVG）。
• 已注册 Service Worker（Lighthouse PWA 审计及部分 Chromium 变体要求；强烈建议所有目标平台均注册，以启用离线支持和推送）。
• 捕获并延迟 beforeinstallprompt，以便在 Android 和桌面端适时展示安装提示。
• 为 Safari 用户提供 iOS 专属的“添加到主屏幕”指引。