Web 应用程序清单指南
Web 应用程序清单 (site.webmanifest) 是一个 JSON 文件，它告诉可安装浏览器您的应用程序的名称、颜色、显示模式以及在主屏幕上使用的图标大小。将其与“<link rel='manifest' href='/site.webmanifest'>”链接可在桌面和 Android 上启用 Chrome 和 Edge PWA 安装提示。将其与 192×192 和 512×512 PNG 图标配对（均由 favicon generator 导出），以获得完整的 PWA 图标设置。
Web 应用程序清单是一个使用 `application/manifest+json` MIME 类型的 JSON 文本文件。它位于您选择的任何 URL 中，但约定是位于域根的 /site.webmanifest。您可以使用“<head>”元素内的“<link rel='manifest' href='/site.webmanifest'>”从 HTML 链接它。浏览器在评估是否显示安装提示或如何在安装后呈现应用程序时读取清单。
图标数组是清单中与网站图标最相关的部分。每个条目指定 src（图像的 URL）、大小（像素尺寸）、类型（MIME 类型）和可选用途（“任何”、“可屏蔽”或“任何可屏蔽”）。至少为启动器图标提供 192×192 PNG，为启动画面提供 512×512 PNG。如果没有这些，Chrome 将不会显示安装提示。
当 PWA 发送网络推送通知时，Android Chrome 在应用程序启动器、最近的应用程序切换器和通知栏中使用 192×192 图标。它必须是 PNG，可以通过其声明的 URL 进行访问而无需重定向，并且如果它位于与清单不同的域中，则可以使用正确的 CORS 标头。 favicon generator 导出 android-chrome-192x192.png 可供直接使用。
512×512 图标用于主屏幕启动后加载应用程序时显示的 PWA 启动画面、桌面上 Chrome 和 Edge 中的安装对话框预览以及 Chrome 操作系统应用程序启动器。清单中缺少 512×512 条目不会阻止安装，但会导致启动屏幕上出现通用浏览器图标。始终包含它以获得完美的安装体验。
可屏蔽图标是 Android 特定的增强功能。 Android自适应图标系统将几何蒙版（圆形、方圆形、泪滴形、圆角矩形）应用于应用程序图标，形状因设备制造商而异。标准“任何”图标的边缘可能会被这些遮罩剪掉。 “可遮罩”图标包括安全区域填充 - 将基本图稿保留在图像中心 80% 的范围内（安全区域圆圈） - 以便可以应用任何遮罩而不会剪切徽标。
要在清单中声明可屏蔽图标，请使用 `'purpose': 'maskable'`: `{ "src": "/android-chrome-512x512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }` 添加相同大小的第二个条目。您还可以将 `'purpose': 'any maskable'` 合并到一个条目上。使用生成器的可屏蔽导出选项生成具有额外填充的可屏蔽图标。
name 和short_name 字段控制您的应用程序在主屏幕和应用程序抽屉中的标记方式。 `name` 是安装提示期间显示的完整应用程序名称。 `short_name` 是主屏幕上图标下方的标签 - 将其控制在 12 个字符以内，以避免在较小的屏幕上被截断。出现安装提示时需要两个字段。
theme_color 字段设置当用户导航到您的站点时（不仅仅是安装了 PWA 时）Android Chrome 上浏览器地址栏的颜色。它还在独立 PWA 模式下设置工具栏颜色。使用您的主要品牌颜色作为十六进制值。对于不读取清单的 theme_color 的浏览器，请在 HTML 中添加匹配的“<meta name='theme-color' content='#YOUR_COLOR'>”。
background_color 字段控制 PWA 启动和应用程序内容第一次绘制之间显示的启动屏幕背景颜色。将其设置为与应用程序的背景（通常是白色或主要品牌颜色）相匹配，以防止出现刺耳的闪光。如果background_color与您的实际应用背景不匹配，用户会在启动过程中看到颜色跳跃。
显示字段决定了 PWA 安装后的显示方式。 `standalone` 隐藏了浏览器地址栏和导航按钮，使应用程序看起来像本机应用程序。 `minimal-ui` 保留了最小的导航栏。 `fullscreen` 删除所有内容，包括状态栏。 `browser` 显示完整的浏览器 UI。对于大多数 PWA，`standalone` 是正确的选择。如果显示设置为 `browser`，则不会出现安装提示。
start_url 字段指定当用户从主屏幕启动已安装的 PWA 时打开哪个 URL。始终包含此内容 - 如果没有它，Android 将打开发现清单的 URL，该 URL 可能是深层链接页面而不是您的主页。对于大多数网站使用 `'start_url': '/'`，如果您的应用程序需要从特定路由启动，则使用特定 URL。
在 Chrome DevTools 中调试清单问题非常简单。打开 DevTools (F12)，导航到“应用程序”选项卡，然后单击左侧面板中的“清单”。 Chrome 显示清单的解析视图、任何解析错误、图标获取失败以及解释安装提示可能未显示的原因的“可安装性”清单。常见问题包括找不到图标 (404)、MIME 类型错误或缺少 192×192 图标。
正确提供清单需要两个服务器端配置。首先，必须使用 `Content-Type: application/manifest+json` 来提供该文件。其次，如果您的图标位于 CDN 上或来自清单的不同来源，则图标响应必须包含适当的 CORS 标头（`Access-Control-Allow-Origin: *` 或您的域）。图标文件上缺少 CORS 标头将导致浏览器将清单视为无效。
对于自动生成清单的框架，请验证生成的文件是否包含您的实际图标大小和颜色。 Next.js 从 /app/manifest.ts 导出中生成清单。创建React App会生成/public/manifest.json。 Vite 默认情况下不生成清单 - 手动创建一个。在所有情况下，更新图标数组以引用实际的品牌图标文件而不是默认的占位符图标。
工作原理
- 1
生成 192×192 和 512×512 PNG 图标
将您的 512×512 徽标 PNG 或 SVG 上传到 [favicon generator](tool:favicon-generator)。下载包包括 android-chrome-192x192.png 和 android-chrome-512x512.png 可以直接使用。
- 2
创建site.webmanifest
创建至少包含以下内容的 JSON 文件：`name`、`short_name`、`icons`（192 和 512 条目）、`theme_color`、`background_color` 和 `display: 'standalone'`。生成器包包括预填充的清单模板。
- 3
使用正确的 MIME 类型提供清单
配置您的服务器以使用 `Content-Type: application/manifest+json` 提供 .webmanifest 文件。在 Apache 上，将 `AddType application/manifest+json .webmanifest` 添加到 .htaccess。在 Nginx 上，将 MIME 类型添加到 mime.types。
- 4
链接 HTML 中的清单
在“<head>”中添加“<link rel='manifest' href='/site.webmanifest'>”。还为不读取清单 theme_color 的浏览器添加“<meta name='theme-color' content='#YOUR_COLOR'>”。
- 5
使用 Chrome DevTools 进行验证
打开 Chrome DevTools > 应用程序 > 清单。确认没有显示错误并且所有图标均已解析。检查“可安装性”部分，了解 PWA 安装提示满足或未满足的确切条件。
- 6
测试安装提示
在 Android Chrome 上，导航到您的站点。如果满足所有条件，Chrome 会在浏览器菜单中显示安装横幅或“添加到主屏幕”选项。安装后，验证启动屏幕背景颜色和主屏幕图标是否正确呈现。
立即尝试
生成您的 PWA 图标包
Favicon 生成器常见问题
基本网站是否需要网络应用程序清单？+
否 — 仅当您希望在 Android 和桌面 Chrome/Edge 上出现 PWA 安装到主屏幕提示时。 favicon.ico 单独处理浏览器选项卡。当您想要启用更丰富的移动和桌面安装体验时，请添加清单。
Web 应用程序清单中的图标大小是什么？+
最低：192×192（Android 启动器）和 512×512（启动画面和安装预览）。添加两种尺寸的可屏蔽变体以支持自适应 Android 图标，如果您需要额外的密度覆盖范围，则添加 384×384。
清单中的 theme_color 和 background_color 有什么区别？+
theme_color 设置浏览器地址栏和工具栏颜色。 background_color 设置应用程序首次绘制之前显示的启动屏幕背景颜色。将两者设置为与您的品牌相匹配，以获得无缝的安装和启动体验。
为什么 Chrome 没有显示我的 PWA 的安装提示？+
最常见的原因是：清单丢失或无效、缺少 192×192 图标、返回 404 的图标、未使用正确的 MIME 类型提供清单或未通过 HTTPS 提供站点服务。使用 Chrome DevTools > Application > Manifest 查看确切的可安装失败原因。
什么是可屏蔽图标？我需要一个吗？+
可遮罩的图标包括安全区域填充，因此 Android 可以应用圆形或方圆形遮罩，而不会剪裁您的徽标。您需要一个主屏幕图标，以便在使用非方形自适应图标形状的 Android 设备上看起来正确。在清单图标数组中使用 `'purpose': 'maskable'` 声明它。
我可以在 Web 应用程序清单中使用 SVG 图标吗？+
Chromium 在某些清单图标上下文中支持 SVG，但 PNG 是跨浏览器安装 UI 的普遍安全的默认值。始终包含 PNG 192 和 512 条目。您可以在它们旁边添加 SVG 条目，不会有任何损害。
如何检查我的网络清单是否有效？+
打开 Chrome DevTools (F12) > 应用程序 > 清单。 Chrome 显示解析错误、图标获取失败和完整的可安装性检查表。修复所有报告的问题，然后使用 Chrome 地址栏中的“添加到主屏幕”选项重新测试安装提示。