OpenPWAStore
返回 News
Guide · May 20, 2026

PWA 图标要求在各浏览器平台并不统一，虽然 manifest 标准存在

PWA 图标看似简单，直到你跨平台测试。其实际有效要求如下。

OpenPWA Editorial2 min read
中文English
PWA 图标要求在各浏览器平台并不统一，虽然 manifest 标准存在 cover

为什么 PWA 图标在不同平台仍然不同

Web App Manifest 规范明确定义了图标字段：src、sizes、type 和 purpose。但实践中，每个浏览器平台对图标的解读不同，而 iOS Safari 在可安装图标上几乎完全忽略 manifest。

MDN 的 manifest 文档说明了标准格式，但平台特定行为意味着你不能依赖单一图标声明到处通用。

Manifest 标准到底覆盖了什么

必须的图标字段

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

根据 MDN：

  • src：图标图片路径（必填）
  • sizes：尺寸，格式为 宽x高（针对栅格图标）
  • type：MIME 类型，如 image/png 或 image/webp
  • purpose：图标的使用方式（any、maskable 或 any maskable）

Purpose 值的意义

  • any：标准图标使用。浏览器可能裁剪或填充。
  • maskable：为 Android 上的安全区遮罩设计。浏览器会将你的图标适配进某种形状（圆、圆角方等），而不切断核心视觉元素。

Android Chrome 的要求

核心尺寸

MDN 指出，Android Chrome 通常至少要求：

  • 192×192px 用于自适应启动器图标
  • 512×512px 用于 Play Store 列表及高密度屏幕

Maskable 图标

Android 设备会对图标应用自适应形状（adaptive icons）。purpose: "maskable" 的图标应包含安全区：

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

Maskable 最佳实践：

  • 将 Logo 置于画布约 66.7% 的中心区域
  • 确保没有关键元素接触边缘（可能被裁剪）
  • 使用 Chrome DevTools 的 "App manifest" 验证工具测试安全区

常见失败原因

  • 缺少 512×512px 尺寸：Chrome 可能在可安装性检查中失败
  • 缺少 maskable 版本：Android 在非方形容器上会拙劣裁剪标准图标

iOS Safari 的“超常例外”

iOS Safari 不会使用 manifest 作为“添加到主屏幕”的图标来源。它依赖：

<link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon-180.png">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="apple-mobile-web-app-title" content="My App">

iOS 图标尺寸现状

  • 180×180px 是当前标准（Retina 设备用作主屏幕图标）
  • 历史上使用过 57×57、72×72、114×114、144×144（现已弃用）
  • Safari 不尊重 maskable purpose；它只会创建圆角方

Safari 破坏了什么

  • 启动画面行为：Safari 会基于你的 apple-touch-icon 和页面背景色自动生成启动画面。它不会为原生风格启动画面尊重 manifest 中的截图。
  • 横向启动画面：Safari 会把纵向启动画面拉伸到横向模式；manifest 宣告不能绕过。

Microsoft Edge 的行为

Edge（基于 Chromium）紧随 Chrome 图标要求，但存在平台特定差异：

  • Windows 任务栏图标：偏大尺寸（96×96px 或以上）以获得清晰渲染
  • 开始菜单磁贴：若需要 Windows 品牌风格，可使用磁贴特定元数据
  • 评级徽章：对于 Xbox/Windows Store 分发，你可能需要带透明度的额外资源

Edge 在 Windows 11 圆角布局上会尊重 maskable purpose。

Firefox 的立场

Firefox for Android 支持自动添加到主屏幕（A2HS），并使用 manifest 中的图标集：

  • 最低 192×192px 用于可安装性
  • Maskable 支持：Firefox 可以尊重 maskable purpose，但可能不会像 Chrome 那么激进地应用自适应形状
  • 桌面 Firefox：图标出现在地址栏和书签菜单；manifest 主要影响移动端安装

跨浏览器图标清单

通用覆盖的最低规格

| 尺寸 | Purpose | Android | iOS | Edge | Firefox | |------|---------|---------|-----|------|---------| | 192×192px | any | ✅ 必须不可 | ❌ 使用 apple-touch-icon | ✅ | ✅ 必须不可 | | 512×512px | any | ✅ 推荐 | ❌ | ✅ | ✅ 推荐 | | 512×512px | maskable | ✅ 强烈推荐 | ❌ | ✅ | 可选 | | 180×180px | apple-touch-icon | ✅ 可能回退 | ✅ 必须不可 | ❌ | ❌ | | 384×384px | any | 可选（HiDPI） | ❌ | 可选 | 可选 | | 1024×1024px | any | Play Store 元数据 | ❌ | 可选 | ❌ |

格式建议

| 格式 | 优点 | 缺点 | 覆盖度 | |--------|------|------|----------| | PNG | 通用，质量好 | 文件较大 | 100% | | WebP | 文件小，质量好 | 旧 Safari 可能不支持 manifest 中的 WebP | 现代浏览器 | | SVG | 分辨率无关 | manifest 中大多数平台不支持 | 有限（用于行内/favicons） |

安全选择：manifest 图标坚持用 PNG。在有浏览器支持把握的地方使用 WebP 提升性能。

常见陷阱

仅 manifest 无法在 iOS 上正确安装。

2. 错误的长宽比

  • 图标应为正方形（1:1）。非正方形图标可能被拒绝或拙劣裁剪。
  • 某些平台对非正方形尺寸进行非等比缩放。

3. Android 上没有 maskable 版本

非方形容器（Android 13+ 设备）的用户，如果没有 maskable 声明，会看到拙劣裁剪的图标。

4. 资源尺寸未优化

大尺寸图标（1024×1024px）出现在 manifest 中会拖慢下载，并在计费网络下失败。在商店列表中引用大文件，而非 manifest。

5. 忽视背景色

manifest 中的 background_color 影响某些平台的启动画面生成：

{
  "background_color": "#FF6B00"
}

实操落地

图标生成工具

  • Maskable.app：测试 maskable 图标的安全区
  • PWA Asset Generator（GitHub）：从源 SVG/PNG 生成所有必要尺寸
  • Progressier PWA Tool：提供 manifest 与图标生成指引

验证步骤

- 验证图标在 Chrome 安装提示中出现正确 - 在预览中检查 maskable 安全区

  1. Chrome DevTools → Application → Manifest → 点击 "Add to home screen"

- 验证 180×180px apple-touch-icon 出现 - 检查启动画面生成

  1. Safari → 分享 → 添加到主屏幕（iOS）

- 验证图标在缩放时清晰渲染

  1. Edge → 已安装应用 → 任务栏检查

- 确认安装提示显示正确图标

  1. Firefox Android → 菜单 → "Add to Home Screen"

对于 PWA 市场

若通过 PWABuilder 或应用商店分发：

  • Play Store：Maskable 512×512px 图标 + 商店专用营销资源
  • App Store：需要完整的 iOS 应用商店图标套件（除非用 TWA 包装，否则与 PWA 不相关）
  • Windows：可选磁贴徽章模板
  • Samsung Internet：可能请求 Galaxy Store 的额外图标尺寸

标准差距

W3C manifest 提供了标准，但平台实现存在显著差异：

  • Safari 的传统 apple-touch-icon 仍主导 iOS 安装
  • 自适应图标形状（Android 的安全区）没有 manifest 级别的精准控制
  • 启动画面仍是平台特定（自动 vs. 声明式）

应对：同时提供 manifest 与 apple-touch-icon 元数据、生成 maskable 版本，并在真实设备上测试。

下一步

  1. 对照此清单审计当前图标集
  2. 生成缺失的 maskable 版本与 apple-touch-icon
  3. 在 Chrome（Android）、Safari（iOS）、Edge 与 Firefox 测试安装提示
  4. 将图标尺寸监控加入构建管线
  5. 为团队记录平台特定预期

忽略任何单一尺寸、等浏览器会宽容错误，但用户会注意到缩放、裁剪或缺失的图标——尤其在竞争对手优化了每个平台的时候。