# 从原生应用迁移到 PWA

> 什么是 PWA，以及它依赖的两块基础：提供安装元数据的 manifest 和能够离线服务的 Service Worker，各附最小示例。

完成本指南后，你会有一份把原生应用功能逐项映射到 Web 等价物及其兼容性条目的范围清单、一份让现有 Web 产品可安装的 manifest 与 Service Worker，以及针对各操作系统安装与卸载时刻的方案（它们与商店应用的行为不同）。Progressive Web App 是一种由操作系统像平台专属应用一样安装与启动的 Web 应用；它通过 URL 交付，在下次加载时更新，并运行在安装它的那个浏览器的引擎中。

你需要原生应用的功能列表、产品的 Web 版本（或决定去做一个），以及一个通过 HTTPS 提供的域名。

## 对照 Web 能力盘点原生功能

列出原生应用依赖的每一项系统集成，在承诺之前先到本站逐项查证：推送通知（[Web Push](/zh/reference/notifications/web-push/)）、应用图标角标（[角标](/zh/reference/installation/badging/)）、分享到应用（[Share target](/zh/reference/manifest/share-target/)）、打开文件（[`file_handlers`](/zh/reference/manifest/file-handlers/)）、支付（[Payment Request](/zh/reference/capabilities/payment-request/)），以及蓝牙、USB、NFC 等硬件（[能力](/zh/reference/capabilities/)）。每个条目的兼容性表给出逐浏览器、逐系统的支持情况与核验日期；iOS Safari 那一行同样覆盖 iOS 上的 Chrome、Edge 与 Firefox，它们在那里内嵌 WebKit。每项功能记录三列：Web 等价物、缺失的平台、以及你将在那里提供的回退。没有可接受回退的功能，就是在该平台保留原生构建的理由，而这份清单正是这个论证所依据的文档。

## 让 Web 产品可安装

两个文件把站点变成可安装应用。manifest 提供身份与启动元数据；MDN 的可安装性指南列出 Chromium 浏览器要求的成员为 `name` 或 `short_name`、含 192 px 与 512 px 两项的 `icons`、`start_url` 与 `display`：

```json
{
  "id": "/",
  "name": "Field Notes",
  "short_name": "Notes",
  "start_url": "/?source=pwa",
  "scope": "/",
  "display": "standalone",
  "theme_color": "#1f4e79",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}
```

Service Worker 从页面注册，让应用壳在离线时仍然可用，这是原生用户习以为常的行为。注册经过特性检测，没有该 API 的浏览器仍能加载页面：

```js
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js').catch((error) => {
    console.error('Service worker registration failed:', error);
  });
}
```

`/sw.js` 本身在 `install` 阶段预缓存应用壳，在 `fetch` 阶段从缓存应答；[入门](/zh/guides/getting-started/)里有一份可直接复制的完整 worker。manifest 与 Service Worker 彼此独立：桌面版 Firefox 运行 Service Worker，却不从 manifest 安装（MDN："Firefox does not support installing PWAs using a manifest file"），所以要在各自的兼容性条目上分别核实。

## 按操作系统规划安装时刻

商店用户习惯单一的安装路径；PWA 的安装因系统而异，迁移页面必须说清楚。MDN 的安装指南记录了各种形态：桌面版 Chrome 与 Edge 在页面合格时于地址栏显示安装图标；移动浏览器把命令放在浏览器菜单里；iOS 上的 Safari 通过 "Add to Home Screen" 界面安装，自 iOS 16.4 起 Chrome、Edge、Firefox 与 Orion 的分享菜单也有该入口；macOS 14（Sonoma）上的 Safari 增加了 **File** > **Add to Dock…**。MDN 还指出已安装的 PWA 绑定于安装它的浏览器：先从 Edge 安装、再从 Chrome 安装的用户会得到两个副本。如果原生应用在过渡期内仍留在商店，就把它声明在 `related_applications` 中，并用 `navigator.getInstalledRelatedApps()`（仅限顶层安全上下文）对仍装着它的用户隐藏 Web 安装推广。

## 告诉用户如何启动与删除

启动行为与原生应用一致：MDN 写道 "clicking on the application icon opens the PWA, even when the user is offline"，当 manifest 要求时会在没有浏览器界面的独立窗口中打开。删除是客服工单的来源，所以按 MDN 指南逐系统写明：桌面上，已安装窗口的菜单提供卸载链接，Chrome 在 `chrome://apps`、Edge 在 `edge://apps` 列出已安装应用；大多数移动系统上，PWA 像普通应用一样从应用设置中卸载。

:::observed
MDN 的 "Installing and uninstalling web apps" 指南（2026-10-03 读取）记载，在 iOS 上，从 Safari 安装的 PWA "are listed and searchable from the 'App Library' screen, but are not listed along with other installed applications under 'Settings'"，长按图标会出现删除书签的界面：从主屏幕移除图标即删除该 PWA。迁移 FAQ 若让 iOS 用户去「设置 > 通用 > iPhone 储存空间」里找（原生应用出现的地方），就把他们引向了一个 Web 应用不在其中的列表。
:::

## 另请参阅

- [入门](/zh/guides/getting-started/)
- [让它可安装](/zh/guides/installable/)
- [通过应用商店分发 PWA](/zh/guides/app-store-distribution/)
- [iOS 与 Safari 上的 PWA](/zh/reference/platforms/ios-safari/)
- [Installing and uninstalling web apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Installing)（developer.mozilla.org）
- [Making PWAs installable](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable)（developer.mozilla.org）
- [Using Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)（developer.mozilla.org）