可遮罩图标（maskable icon）是什么？什么时候需要？

可遮罩图标是专为 Android 自适应图标设计的变体，由 OS 按设备厂商规定的形状（圆形、方圆形、圆角矩形、水滴形等）进行裁剪。所有面向 Android 用户的 PWA 都应该提供可遮罩图标，否则 Android 9+ 设备上的图标会被默认加上灰白色背景，与系统其他图标格格不入。

manifest.json 中的 "any" 和 "maskable" 有什么区别？

purpose: "any" 是标准图标，按原样渲染，保留透明度，用于 iOS 主屏、Windows 磁贴、macOS Sonoma 之前的系统。purpose: "maskable" 是自适应图标，OS 会按形状裁剪，必须使用不透明背景并预留 10% 安全边距。两者应该用不同的图片文件分别声明，不要合并。

Chrome 安装 PWA 后图标不显示怎么解决？

按以下顺序排查：(1) 必须用 Chrome 安装，不要用 Firefox、Edge、Samsung Internet，它们经常创建快捷方式而非真正的 PWA；(2) 检查 HTML head 中是否有标签；(3) 打开 DevTools → Application → Manifest 验证每个图标 URL 都能正常加载；(4) 在设置 → 应用中卸载 PWA 后用 Chrome 重新安装。

单个 PWA 图标文件应该控制在多大？

建议每个图标文件不超过 100KB。文件过大会延迟 PWA 的安装提示和首屏加载，对于网络慢的用户影响明显。可以用 pngquant、oxipng 等工具进行无损压缩。

可遮罩图标必须用不透明背景吗？

是的，必须用不透明背景。如果可遮罩图标使用透明 PNG，系统在应用遮罩时会用默认的灰色或白色填充透明区域，与你的品牌色形成强烈反差。标准图标（any）可以保留透明背景。

2025/08/28

PWA 图标完整指南：尺寸、安全区域与 manifest.json 配置

Q: PWA 图标必须提供哪些尺寸？

Chrome 的安装条件要求 manifest.json 中至少包含 192×192 和 512×512 两个 PNG 图标。192×192 用于安装提示和主屏图标，512×512 用于启动画面和高分辨率屏幕。若要支持 Android 自适应图标，还需额外提供这两个尺寸的 maskable 版本。

Q: 只提供 512×512 一个尺寸可以吗？

可以通过 Lighthouse 的安装性检查，但不推荐。Chrome 在安装提示、主屏等小尺寸场景下会把 512×512 缩小到 192×192，可能产生轻微模糊。同时提供 192×192 和 512×512 能确保所有场景下都是像素级清晰。

Q: Lighthouse 提示 "Manifest doesn't have a maskable icon" 怎么修复？

在 manifest.json 的 icons 数组中新增一项，purpose 字段设为 "maskable"，src 指向一张独立的、符合 80% 安全区域规范的图片。注意 Lighthouse 只检查 manifest 声明是否存在，不会检查图片是否真的符合安全区要求，添加后还需要用 Chrome DevTools 的安全区预览功能手动验证。

Q: PWA 图标可以用 SVG 格式吗？

不推荐。SVG 在 PWA 中的支持非常不一致——Chrome 支持 manifest 中的 SVG 图标，但 iOS Safari 和部分 Android 启动器不支持。稳妥做法是用 PNG 提供 192×192 和 512×512，SVG 可作为补充项添加但不能替代 PNG。

PWA 图标的完整参考：必备尺寸 192×192 与 512×512、80% 安全区域规则、可遮罩图标（maskable icon）配置，以及 Lighthouse 报错修复方法。

一句话回答

PWA 需要在 manifest.json 中声明至少两个 PNG 图标：192×192 和 512×512。如果要支持 Android 自适应图标，还需要这两个尺寸的可遮罩（maskable）变体，并将关键内容保留在中心 80% 安全区域内（四周各留 10% 边距）。purpose: "any" 和 purpose: "maskable" 必须分开声明，切勿合并为 "any maskable"。

PWA 图标尺寸速查表

尺寸	是否必需	purpose	使用场景
192×192	✅ 必需	`any`	Chrome 安装提示、Android 主屏
512×512	✅ 必需	`any`	启动画面、Play Store 预览、高 DPI 屏
192×192 maskable	🟡 强烈推荐	`maskable`	Android 自适应图标
512×512 maskable	🟡 强烈推荐	`maskable`	高 DPI 设备的启动画面
144×144、168×168、384×384	可选	`any`	特定屏幕密度的像素级精确渲染
1024×1024	可选	`any`	未来超高 DPI 屏、营销素材

最小可用配置：1 个 192×192 标准图标 + 1 个 512×512 标准图标 + 1 个 512×512 可遮罩图标。Chrome 会自动在尺寸间缩放。

purpose 字段的两种取值

PWA 图标通过 manifest.json 中的 purpose 字段告诉浏览器该如何渲染。

`purpose: "any"`——标准图标

按原样渲染，保留透明度。
用于 iOS 主屏（添加到主屏时）、Windows 磁贴、macOS Sonoma 之前的系统，以及没有 maskable 图标时的回退方案。
设计时让 Logo 占满整个图标，无需额外留白。

`purpose: "maskable"`——自适应图标

由 OS 裁剪成平台特定形状（圆形、方圆形、圆角矩形、水滴形）。
现代 Android 启动器的自适应图标必备。
必须使用不透明背景，并遵守 80% 安全区域规则。

⚠️ 不要使用 `purpose: "any maskable"`

把两种用途合并到同一条目是 web.dev 官方明确反对的写法，Chrome DevTools 也会发出警告。原因是：可遮罩图标本身已预留 10% 边距，当 OS 把它当作标准 any 图标使用时，边距会被保留——结果你的图标看起来比其他应用小 20%。

正确做法是在 manifest 中提供两个独立的图标条目。

80% 安全区域规则

可遮罩图标的规范定义了一个最小安全区域：以图标中心为圆心、半径为图标宽度 40% 的圆形区域。等价说法是，所有关键内容必须保留在图标中心 80% 的区域内。

完整图标尺寸：512 × 512 px
安全区域：    410 × 410 px（中心 80%）
四周边距：    各 51 px（10%）
安全区形状：   半径 205 px 的圆形

内容布局原则：

安全区域内：Logo 主体、文字、核心视觉元素。
安全区域外（10% 外环）：仅放置背景色或图案，假设这部分会被裁掉。

之所以是 80%，是因为最激进的裁剪形状（圆形）会从四边各切掉约 10%。可能被应用的遮罩形状包括：

圆形（最严格——Pixel 设备、Gnome 桌面快捷方式）
方圆形（Samsung One UI）
圆角矩形（原生 Android、iOS 风格）
水滴形（部分 Android 启动器）

如果你的 Logo 顶到边缘，圆形遮罩就会切到 Logo 上。80% 安全区能保证图标在任何遮罩形状下都能完整呈现。

完整的 `manifest.json` 配置

推荐使用四条独立的图标声明——两条用于标准渲染，两条用于自适应图标：

{
  "name": "你的 PWA 名称",
  "short_name": "应用简称",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-maskable-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icons/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

别忘了在 HTML 的 <head> 中引用 manifest：

<link rel="manifest" href="/manifest.json" />
<meta name="theme-color" content="#000000" />

如何从 Logo 制作可遮罩图标

最常见的错误是直接把标准 Logo 当作 maskable 图标使用——结果在 Android 上被裁切。正确步骤如下：

准备 512×512 的源图。 高分辨率源图便于后续缩放。
添加不透明背景。 使用与品牌色一致的纯色背景。可遮罩图标用透明背景时，OS 会用默认的灰白色填充，破坏品牌一致性。
将 Logo 缩放至中心 80% 区域内。 512×512 图标对应的可放置区域是 410×410，居中放置。
背景延伸到完整边缘。 外侧 10% 圆环只保留背景色，Logo 不能触及边缘。
分别导出标准版和可遮罩版。 标准版满铺，可遮罩版带 80% 安全区。
从 512×512 缩小生成 192×192。 不要分别编辑两份源图，统一从大尺寸缩小避免不一致。

快速方案：使用我们的 PWA 图标生成器，上传一次 Logo 即可自动生成标准版和可遮罩版的全部尺寸，附带实时安全区域预览。

如何测试 PWA 图标

Chrome DevTools（官方方法）

验证可遮罩图标最可靠的方式：

在 Chrome 中打开你的 PWA（桌面或通过远程调试连接 Android）。
打开 DevTools → Application 面板。
在侧栏找到 Icons 区块。
勾选 "Show only the minimum safe area for maskable icons"。

如果你的 Logo 和关键内容在裁剪后依然可见，说明图标在所有遮罩形状下都安全。

真机测试

DevTools 和在线预览覆盖不了所有边界情况。上线前务必：

至少在一台 Pixel（原生 Android）和一台三星（One UI）设备上安装测试。
检查图标在应用抽屉、主屏、任务切换器、通知栏中的呈现。
验证安装时的启动画面是否使用了正确的图标。
在浅色和深色系统主题下都测试一次。

常见错误与修复

Lighthouse 报错 "Manifest doesn't have a maskable icon"

原因：manifest.json 中没有 purpose: "maskable" 的图标条目。

修复：按上面的 manifest 示例新增一条独立的 maskable 图标条目。注意 Lighthouse 只检查声明是否存在，不会验证图片是否真的符合安全区域要求。添加后还要用 Chrome DevTools 手动确认图标内容。

Chrome 在 Android 安装 PWA 后图标不显示

按优先级排查：

浏览器选错了：必须用 Chrome。Firefox、Edge、Samsung Internet 经常创建桌面快捷方式而非真正的 PWA 安装。
缺少 manifest 引用：HTML <head> 中必须有 <link rel="manifest" href="/manifest.json">。
图标 URL 返回 404：打开 Chrome DevTools → Application → Manifest，确认每个图标 URL 都能访问。如果 manifest 不在根目录，相对路径容易出错。
缓存的旧安装：到「设置 → 应用」卸载 PWA，再用 Chrome 重新安装。

Android 上图标周围出现白色背景

原因：把透明的 PNG 用作了可遮罩图标。Android 系统会用默认色（通常是灰白色）填充透明区域，再应用遮罩。

修复：重新生成可遮罩版本，使用不透明背景，颜色匹配品牌色。标准 any 图标可以继续保持透明。

图标在主屏上比其他应用图标小一圈

原因：把可遮罩图标用作了标准 any 用途（常见于使用了 "any maskable"）。为遮罩预留的 10% 边距在不裁剪的场景下被保留，导致视觉上偏小。

修复：提供两份独立的图片文件——purpose: "any" 用满铺版本，purpose: "maskable" 用带安全区的版本。

平台差异速览

Android（WebAPK）

Chrome 在 Android 上安装 PWA 时会生成 WebAPK——一个真正的 Android 安装包——使用 manifest 中的图标。可遮罩图标用于自适应主屏图标，标准图标用于安装提示横幅。

iOS

iOS 不读取 manifest 的 icons 数组，而是使用 apple-touch-icon。HTML 中需要单独声明：

<link rel="apple-touch-icon" href="/icons/apple-touch-icon-180.png" />

推荐尺寸 180×180 PNG，不要透明背景——iOS 会用白色填充透明区域。如果需要完整体验，还要提供 apple-touch-startup-image 启动画面。

Windows 和 macOS

Windows PWA：使用 any 图标用于任务栏和磁贴渲染，忽略 maskable 图标。
macOS Sonoma+：在 Dock 中优先使用 maskable 图标，没有则回退到 any。

最佳实践清单

purpose: "any" 和 purpose: "maskable" 分开两套图片文件。
可遮罩图标四周各留 10% 边距，使用不透明背景。
单个图标文件控制在 100KB 以内（用 pngquant 等工具压缩）。
至少提供 192×192 和 512×512 两个尺寸。
为 iOS 单独提供 apple-touch-icon（180×180）。
上线前用 Chrome DevTools 的安全区域开关验证一遍。

作者

yifu

分类

一句话回答 PWA 图标尺寸速查表 purpose 字段的两种取值 purpose: "any"——标准图标 purpose: "maskable"——自适应图标 ⚠️ 不要使用 purpose: "any maskable"80% 安全区域规则完整的 manifest.json 配置如何从 Logo 制作可遮罩图标如何测试 PWA 图标 Chrome DevTools（官方方法）真机测试常见错误与修复 Lighthouse 报错 "Manifest doesn't have a maskable icon"Chrome 在 Android 安装 PWA 后图标不显示 Android 上图标周围出现白色背景图标在主屏上比其他应用图标小一圈平台差异速览 Android（WebAPK）iOS Windows 和 macOS 最佳实践清单常见问题 PWA 图标必须提供哪些尺寸？只提供 512×512 一个尺寸可以吗？purpose: "any maskable" 这种写法可以用吗？Lighthouse 提示 "Manifest doesn't have a maskable icon" 怎么修复？PWA 图标可以用 SVG 格式吗？Chrome 在 Android 安装 PWA 后图标不显示怎么解决？相关工具

邮件列表

加入我们的社区

订阅邮件列表，及时获取最新消息和更新

PWA 图标完整指南：尺寸、安全区域与 manifest.json 配置

一句话回答

PWA 图标尺寸速查表

purpose 字段的两种取值

`purpose: "any"`——标准图标

`purpose: "maskable"`——自适应图标

⚠️ 不要使用 `purpose: "any maskable"`

80% 安全区域规则

完整的 `manifest.json` 配置

如何从 Logo 制作可遮罩图标

如何测试 PWA 图标

Chrome DevTools（官方方法）

真机测试

常见错误与修复

Lighthouse 报错 "Manifest doesn't have a maskable icon"

Chrome 在 Android 安装 PWA 后图标不显示

Android 上图标周围出现白色背景

图标在主屏上比其他应用图标小一圈

平台差异速览

Android（WebAPK）

iOS

Windows 和 macOS

最佳实践清单

常见问题

PWA 图标必须提供哪些尺寸？

只提供 512×512 一个尺寸可以吗？

`purpose: "any maskable"` 这种写法可以用吗？

Lighthouse 提示 "Manifest doesn't have a maskable icon" 怎么修复？

PWA 图标可以用 SVG 格式吗？

Chrome 在 Android 安装 PWA 后图标不显示怎么解决？

相关工具

作者

分类

更多文章

Logo 资源生成最佳实践

2025 年不同浏览器的网站图标优化

开发者实现 Logo 资源指南

邮件列表