# 桌面端 PWA 安装：Chrome、Edge 及更多

> PWA 安装在 Windows、macOS、Linux 和 ChromeOS 上的工作方式——安装 UI、窗口管理、操作系统集成以及各平台差异。

**一句话：** Windows、macOS、Linux 和 ChromeOS 上的 Chrome 和 Edge 允许用户将 PWA
安装为独立桌面应用，拥有各自的窗口、任务栏/Dock 条目和操作系统级集成——通过
`beforeinstallprompt` 或浏览器的环境安装图标触发。

## 桌面端的安装触发器

与 Android 不同，桌面端的 Chromium 不显示 mini-infobar。安装入口包括：

- **地址栏图标** — 一旦 PWA 满足[可安装性条件](/zh/reference/installation/installability-criteria)，
  Chrome 或 Edge 的地址栏就会出现一个小的"安装"图标（带下载箭头的屏幕图案）。
- **浏览器菜单** — Chrome：三点菜单 → "安装 [应用名称]…"；
  Edge：三点菜单 → 应用 → 安装 [应用名称]。
- **自定义页内提示** — 你的代码捕获 `beforeinstallprompt`，存储它，
  并在点击处理器中调用 `prompt()`。这是实现可控安装 UX 的推荐方式。

`beforeinstallprompt` 在桌面端的触发方式与 Android 相同；同一套代码路径适用于所有平台。

## 安装后的窗口管理

安装后，PWA 在独立的**应用窗口**（无浏览器标签、无地址栏、无浏览器工具栏的操作系统窗口）中打开。
窗口由浏览器引擎管理，但由操作系统呈现：

- **Windows：** 应用出现在任务栏中。Alt+Tab 可切换到它。可固定到"开始"菜单。
- **macOS：** 应用出现在 Dock 中。Cmd+Tab 包含它。Spotlight 可找到它。
- **Linux：** 在应用程序启动器（GNOME、KDE 等）中以 `.desktop` 条目出现。
- **ChromeOS：** 出现在启动器货架和搜索中。

窗口标题和图标来自清单的 `name` 和 `icons`。
窗口行为（大小、位置）遵循清单中指定的 `launch_handler` 和 `window_controls_overlay` 设置。

## 窗口控件叠层（WCO）

桌面端的 Chrome 和 Edge 支持 `display_override` 中的 `window-controls-overlay`，
让网页内容可以延伸到标题栏区域。操作系统原生的关闭/最小化/最大化按钮仍保留在原处；
你的 HTML 填充其余的标题栏空间：

```json
{
  "display": "standalone",
  "display_override": ["window-controls-overlay"]
}
```

```css
.title-bar {
  /* 在标题栏区域定位内容 */
  position: fixed;
  top: env(titlebar-area-y);
  left: env(titlebar-area-x);
  width: env(titlebar-area-width);
  height: env(titlebar-area-height);
}
```

WCO 仅限桌面端；在移动端无效，会回退到 `standalone`。

## 各平台说明

### Windows（Chrome / Edge）

Chrome 和 Edge 均支持在 Windows 10 和 11 上安装 PWA。Edge 比 Chrome 更深入地将 PWA
注册到 Windows Shell（开始菜单、跳转列表）。两者都会在用户的应用文件夹中生成 `.lnk` 快捷方式。
Edge 的"应用"中心（`edge://apps`）用于管理已安装的 PWA。

### macOS（Chrome / Edge）

在 macOS 上，Chrome 和 Edge 都会在 `~/Applications/Chrome Apps/` 或
`~/Applications/Microsoft Edge Apps/` 中创建应用包。应用出现在 Spotlight 和访达中。
macOS 原生功能如全屏模式和空间（Spaces）均可正常使用。
应用**不会**出现在 Mac App Store 中。

### Linux（Chrome）

Chrome 在 `~/.local/share/applications/` 中创建 `.desktop` 文件。
应用出现在系统启动器中。基于 Chromium 的 Linux 版 Edge 也支持 PWA 安装。

### ChromeOS

ChromeOS 与 PWA 安装紧密集成。通过 Chrome 在 ChromeOS 上安装的 PWA 出现在 ChromeOS 启动器中，
可以固定到货架，并作为一等应用运行。ChromeOS 还与 Google Play 商店原生集成以支持 TWA
（详见 [TWA 参考文档](/zh/reference/installation/twa)）。

### macOS Safari（Sonoma 及以上）

macOS Sonoma（14.0，2023 年底）引入了 **Web 应用**——用户可以从 Safari 的"文件"菜单
→ "添加到 Dock"来安装网站。已安装的应用在没有地址栏的 Safari 窗口中打开。
`beforeinstallprompt` **不会**在 Safari 中触发；安装完全由用户从 Safari 菜单发起。
Windows 版 Safari 不作为受支持的平台存在。

### Firefox（桌面端）

桌面版 Firefox **不支持** PWA 安装。地址栏安装图标和 `beforeinstallprompt` 均不存在。
用户可以收藏网站，但无法将其安装为独立应用。

## 在桌面端检测独立模式

```js
const isStandalone =
  window.matchMedia('(display-mode: standalone)').matches ||
  window.matchMedia('(display-mode: window-controls-overlay)').matches;
```

使用此方法在用户已使用已安装应用时隐藏安装按钮。

## 兼容性

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

## 实践检查清单

- [ ] 清单有 `display: standalone`（或 WCO 标题栏应用的相应设置）。
- [ ] 图标至少包含 192 × 192 和 512 × 512 PNG；可考虑添加 SVG `any maskable` 变体。
- [ ] 捕获 `beforeinstallprompt` 并从用户手势中触发。
- [ ] 独立模式检测可在已安装时抑制安装按钮。
- [ ] 如针对 macOS Sonoma Safari，需单独测试"文件 → 添加到 Dock"路径（无 JS API）。
- [ ] 如果使用 WCO，测试窗口调整大小和 `env(titlebar-area-*)` CSS。