如何使用 Web App Manifest 构建和配置 Progressive Web App

Progressive Web App（PWA）是一种将本地应用般的体验带到网站的技术。用户可以在主屏幕上安装您的网站并在离线状态下使用它，完全无需应用商店。本指南介绍如何使用 Web App Manifest 构建 PWA，Web App Manifest 是一个 JSON 文件，可告知浏览器有关您的网络应用的基本信息。

什么是 Progressive Web App 以及为什么它很重要

Progressive Web App 结合了 Service Workers 和 Web App Manifest 等网络技术，提供本地应用般的体验。PWA 可以安装在主屏幕上、离线运行、快速加载并发送推送通知——所有这些都无需应用商店发布。它们对于触及预算受限的设备用户和网络不稳定地区的用户特别有价值。

• 像本地应用一样直接安装到主屏幕
• 通过缓存内容离线运行
• 即使在缓慢的网络上也能快速加载
• 向用户发送推送通知
• 无需应用商店审核或下载障碍

理解 Web App Manifest 文件

Web App Manifest 是一个 JSON 文件，包含有关您的网络应用的元数据——名称、描述、图标、主题颜色和显示模式。浏览器读取此文件以正确安装您的 PWA。将 manifest.json 放在网站根目录中，并在每个 HTML 页面的 中使用 链接它。这个单一文件可告知浏览器安装应用时显示应用所需的所有信息。

• 描述您的网络应用身份的 JSON 文件
• 位于网站根目录中
• 在 HTML 中通过 rel="manifest" 引用
• 包含名称、图标和颜色等基本属性

Manifest 中的必需和推荐字段

基本字段包括：name（完整应用名称）、short_name（主屏幕图标标签的简称，≤12 个字符）、icons（包含尺寸和 MIME 类型的数组）、start_url（入口页面）、display（"standalone" 表示全屏或 "browser" 表示标签页）、background_color（启动屏幕颜色）和 theme_color（系统 UI 颜色）。short_name 必须简洁，因为它显示在主屏幕上的图标下方。现代浏览器处理大多数字段，但较旧的浏览器可能需要其他属性。

• name：安装提示的完整应用名称
• short_name：主屏幕的简称
• icons：包含多个尺寸（192px、512px 等）的数组
• start_url：用户打开应用时要加载的页面
• display："standalone"、"browser" 或 "fullscreen"
• theme_color 和 background_color：操作系统和启动屏幕的颜色

应用图标：所需的尺寸和格式

PWA 需要多个图标尺寸才能在各种设备上正确显示。最小尺寸：192×192 px（主屏幕）和 512×512 px（安装启动屏幕）。144×144 或 256×256 px 等其他尺寸有助于在特定设备上显示。使用具有透明背景的 PNG 或 WebP 格式，以便操作系统可以应用其自己的背景颜色。在 manifest 的 icons 数组中包含每个图标，同时包含尺寸和用途属性（例如，"any" 用于常规用途，或 "maskable" 用于 Android 上的自适应图标）。

• 192×192 px：主屏幕图标的标准尺寸
• 512×512 px：安装启动屏幕和库的大图标
• 144×144 和 256×256 px：额外的备用尺寸
• 推荐使用具有透明度的 PNG 或 WebP 格式
• 适应性图标的可掩膜图标支持（Android）

Service Workers 详解（离线缓存基础）

Service Worker 是在后台运行的 JavaScript 文件，即使关闭网页也会运行。其主要作用是缓存资源（HTML、CSS、图像、JavaScript），使 PWA 能够离线工作。Service Workers 还处理推送通知和后台同步。您不需要复杂的 Service Worker——缓存您的主页和关键静态资源是一个良好的开始。通过在 HTML 中使用调用 navigator.serviceWorker.register() 的简单 JavaScript 代码段在其中注册它。浏览器自动管理其生命周期。

• 在后台独立运行的 JavaScript 文件
• 拦截网络请求以提供缓存资源
• 启用离线功能和更快的加载时间
• 处理推送通知和后台数据同步
• 通过客户端脚本为每个 PWA 注册一次

可安装性标准：使"添加到主屏幕"出现

当 PWA 满足特定条件时，浏览器会显示安装提示：有效的 manifest.json 且包含所需字段、全站使用 HTTPS、已注册的 Service Worker、至少 192×192 px 的图标以及足够的用户参与度（通常在网站上停留 30+ 秒）。Chrome、Edge 和 Samsung Internet 完全支持 PWA 安装提示。iOS Safari 有限制，但允许主屏幕快捷方式。满足所有条件后，许多浏览器会自动显示安装提示，尽管您也可以使用 beforeinstallprompt 事件触发自定义提示。

• 有效的 manifest.json，包含名称、图标和其他必需字段
• 全站强制使用 HTTPS（HTTP 不起作用）
• 已注册且处理 fetch 请求的 Service Worker
• 最少 192×192 px 和 512×512 px 的图标
• 用户参与信号（网站上花费的时间或交互）

使用 Lighthouse 测试 PWA

Google Lighthouse 是内置于 Chrome DevTools 的免费审核工具，可验证 PWA 的合规性。打开 DevTools，转到 Lighthouse 选项卡，选择"PWA"，然后单击"分析页面加载"。Lighthouse 可在性能、无障碍、最佳实践、SEO 和 PWA 合规性方面为应用评分。报告会指出缺少的图标、未注册的 Service Workers、无效的 manifest 和其他问题。在开发过程中定期运行审核，以便尽早发现问题。修复 Lighthouse 确定的问题通常会改进整体网络性能和用户体验。

• 打开 Chrome DevTools 并导航到 Lighthouse 选项卡
• 选择 PWA 并单击"分析页面加载"
• 查看详细报告，突出显示缺少或不正确的字段
• 检查 manifest 有效性、图标尺寸和 Service Worker 注册
• 修复后重新测试以验证改进

PWA vs. 本地应用：优缺点以及何时使用每种

PWA 和本地应用各有优势。PWA 可提供无需应用商店发布的即时访问、自动更新和更低的存储需求。本地应用提供更深入的操作系统集成，如 GPS、麦克风和硬件传感器。PWA 适合内容驱动的应用（新闻、博客、生产力工具），而本地应用在图形密集型游戏和需要直接硬件访问的应用中表现出色。许多公司先推出 PWA 以广泛触及用户，然后在需要专业功能时开发本地应用。

• PWA 优势：无应用商店、即时更新、最小存储空间
• PWA：在预算受限和旧设备上运行良好
• 本地应用优势：可直接访问 GPS、麦克风、传感器
• 本地应用：对于图形密集型游戏性能更优
• 策略：从 PWA 开始，仅在需要特殊功能时才构建本地应用

常见的 Manifest 和 PWA 设置错误

常见问题包括：HTML 中缺少 、图标尺寸或格式不正确、manifest.json 中的 JSON 语法错误、Service Worker 注册失败、非 HTTPS 网站（PWA 需要加密）。另一个常见错误是忘记设置 start_url，这可能导致应用打开到错误的页面。background_color 和图标之间颜色不匹配可能导致启动屏幕显示异常。调试提示：打开 Chrome DevTools，转到"应用程序"选项卡，选择您的网站，并检查 Manifest 部分以立即发现问题。

• HTML 中缺少 标记
• 图标尺寸不正确（至少使用 192×192 和 512×512）
• manifest.json 文件中的 JSON 语法错误
• Service Worker 无法注册或脚本有错误
• 网站未使用 HTTPS（PWA 必需）
• 忘记指定指向正确主页的 start_url