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

> 浏览器显示安装提示或允许用户将应用添加到主屏幕之前，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 参考文档](/zh/reference/installation/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 添加到主屏幕](/zh/reference/installation/ios-add-to-home-screen)。

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

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

## 三星 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 不显示"添加到主屏幕" | 这不是失败——它始终出现在分享菜单中；只是无法用程序触发 |

## 兼容性

当前各浏览器的安装支持数据，请查看[兼容性章节](/zh/compatibility/)。

## 实践检查清单

- [ ] 网站通过 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 专属的"添加到主屏幕"指引。