Manifest 图标与 maskable 图标

一句话： icons 是图像对象数组，浏览器在需要 PWA 图标时从中选取——包括主屏幕、系统应用切换器、启动画面与安装提示。至少提供 192 px 和 512 px 的 PNG 图标，并添加一个 maskable 变体，让 Android 能按设备图标形状对其进行裁剪。

语法

{
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512-maskable.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

每个对象包含四个属性：

属性	是否必填	说明
`src`	是	图像 URL，相对于清单文件解析。
`sizes`	是	以空格分隔的 `宽x高` 字符串（如 `"192x192 256x256"`）。
`type`	建议填写	MIME 类型：`image/png`、`image/webp`、`image/svg+xml`。
`purpose`	可选	`"any"`（默认）、`"maskable"` 或 `"monochrome"`。

最小必需集合

大多数浏览器要求至少一个 192 px 图标才会提供安装提示。512 px 图标用于启动画面。请同时提供：

192x192 PNG — 主屏幕与安装提示
512x512 PNG — 启动画面

单个 sizes: "any" 的 SVG 尚未被所有平台接受为光栅图标的独立替代。

Maskable 图标

Android 会对所有主屏幕图标应用平台定义的形状（圆形、圆角方形、水滴形等）。若无 maskable 图标，浏览器会在图标后添加白色圆形背景以防止裁剪，对于背景透明的图标而言显得突兀。

Maskable 图标要求完整图像内容位于安全区——即图像中心 80% 的圆形区域。外侧 10% 边框内的内容可能被裁剪。

设计规范：

将关键内容（品牌标志、符号）保持在安全区之内。
用背景色填满整个画布，避免操作系统遮罩时出现透明间隙。
发布前使用 maskable.app 测试效果。

通过 "purpose": "maskable" 声明 maskable 图标：

{
  "src": "/icons/icon-512-maskable.png",
  "sizes": "512x512",
  "type": "image/png",
  "purpose": "maskable"
}

也可以在单个条目中列出多个用途：

{
  "purpose": "any maskable"
}

避免将 monochrome 与其他用途混合——它有不同的渲染预期。

图标选择算法

浏览器遍历 icons 数组，根据以下条件选取最合适的图标：

所需的显示尺寸。
与当前上下文匹配的 purpose（Android 异形图标用 maskable，其余用 any）。
大于等于所需尺寸中最接近的尺寸（避免放大）。

建议从小到大排列图标，并为不同用途提供独立的对象，而非完全依赖 "any maskable" 的组合值。

SVG 图标

部分浏览器（Chrome 98+、Edge 98+）支持通过 "sizes": "any" 使用 SVG 图标。SVG 图标缩放性好，在支持平台上无需多个光栅尺寸，但在 iOS 或部分桌面启动器上尚不能作为独立图标使用。将 SVG 作为 192 px 和 512 px PNG 的补充，而非替代。

实践清单

已提供 192 px PNG 图标。
已提供 512 px PNG 图标。
已提供 maskable 变体（512 px，"purpose": "maskable"）。
Maskable 图标内容位于安全区（中心 80%）之内。
Maskable 图标有实色背景填充——无透明区域。
图标 URL 相对于清单位置是正确的。
已在 Android 上测试已安装应用的图标形状，确认 maskable 图标被正确使用。