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

一句话回答

PWA Icon Generator可导出 192px、512px PNG 和 manifest，这是当前工具工作流的常用起点。Manifest 规范并没有统一规定必须提供这两张文件；拥有图标也不代表网站已成为完整可安装 PWA，安装还取决于页面条件和浏览器版本。

PWA 图标尺寸速查表

Chrome 安装推广说明将 192px、512px 与 HTTPS 及其他页面／manifest 条件一起列出。这是浏览器工作流要求，不是 manifest 规范对所有环境的统一规定；手动安装也可能使用不同条件。更大的源图不会自动让细节在小尺寸下清晰。

purpose 字段的两种取值

any 用于不加遮罩时显示的标准图稿；maskable 用于按启动器裁切准备的图稿，应有明确背景并让重要细节处于安全圆内。一张透明 Logo 铺满画布边缘，并不代表适合同时用于两种场景。

purpose: "any"——标准图标

any 用于不加遮罩时显示的标准图稿。透明度取决于设计和目标场景，不是所有标准图标的强制条件。

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

Maskable 图标是按启动器裁切准备的图稿。应让重要部分位于圆形安全区内，并检查目标设备；是否出现外框与实际浏览器、图稿和启动器有关。

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

保留的原标题表达图稿设计取舍，不应理解为语法禁令。purpose: "any maskable" 语法合法。只有同一图稿在有遮罩和无遮罩时都适用才合并；独立文件可分别控制构图与留白。

80% 安全区域规则

512px 方形图标的安全圆中心是 (256, 256)，半径为 204.8px，直径为 409.6px。这不是一个 410px 安全方形。边长 409.6px 的方形，其四角距中心约 289.6px，超出安全半径。

完整方形符号若居中放置，边长约 289px 才能全部落在这个圆内。这是方形图稿的保守计算示例，并不要求所有形状缩成同一大小；圆形或圆角设计可以以不同方式利用空间。应使用叠加层检查所有重要细节。

80% 指安全圆的直径，并不意味着边长 80% 的方形四角也安全。依据为 manifest 规范。

完整的 manifest.json 配置

下方代码假设案例 maskable 文件放在 /icons/，并另外生成两张标准 PNG。请把每个网址与实际文件对应。

{
  "name": "Example app",
  "short_name": "Example",
  "start_url": "/",
  "display": "standalone",
  "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/maskable-icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
    { "src": "/icons/maskable-icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

<link rel="manifest" href="/site.webmanifest">

Manifest 语法允许 purpose: "any maskable"。分别准备文件属于设计建议，原因是已有留白的 maskable 图片在不应用遮罩时可能显得较小；不能把建议写成语法禁止。

如何从 Logo 制作可遮罩图标

下载原创 SVG，进入 Maskable Icon Generator，将留白设为 25%、图稿比例设为 100%、背景设为 #ffffff 后生成。方形图稿占画布一半宽度，落在安全圆内。可与实际案例 ZIP对比。

不要把圆形裁切写入 PNG，应让启动器自行应用形状。不透明背景可以避免系统给透明部分添加不符合设计的底色。

如何测试 PWA 图标

先核对已部署文件，再检查安装后的显示；浏览器标签 favicon 与 PWA 启动器图标需要分别测试。

Chrome DevTools（官方方法）

在 Chrome 打开部署页面，进入 Application → Manifest，核对 manifest 地址、已加载图片、尺寸和实际报错；可用时启用 maskable 安全区预览。流程参阅 DevTools PWA 检查指南。复现时记录浏览器版本，不要仅依赖旧 Lighthouse 警告名称。

真机测试

在项目实际支持的设备上安装，分别检查标准显示和裁切显示。浏览器标签 favicon 属于另一项检查。若通过卸载重装排查，先考虑本地数据和登录状态；重装只是测试手段，不应成为面向用户的通用更新策略。

常见错误与修复

记录实际诊断、浏览器版本和公开网址，先修复文件访问再调整图稿。

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

记录诊断原文和浏览器版本，核对 purpose: "maskable"、真实图片网址和安全圆内的图稿。只补字段不能证明图稿正确；某个 Lighthouse 审计项不保证存在于所有版本。

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

先检查实际启动页加载的 manifest、每张图片的响应、尺寸、子路径、重定向与登录要求，再检查浏览器安装条件和缓存／已安装状态。不能把所有问题都归因于未使用 Chrome。

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

检查透明区域与实际选择的 purpose，明确 maskable 背景并按安全圆调整重要内容。不同启动器的外框处理可能不同。

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

检查是否把留白较大的 maskable 版同时用于普通显示。需要时分开准备较饱满的标准版与保留安全区的 maskable 版。

平台差异速览

按项目实际支持的浏览器和安装入口验证。

Android（WebAPK）

比较多种模拟遮罩，再到真实启动器上查看。PWA manifest 与原生 Android 自适应图标前景／背景资源不是同一套包。原生应用参阅 Android 指南。

iOS

在实际支持的 iOS 版本上检查网站主屏幕图标。专门的 apple-touch-icon 声明是独立集成选项，用法见 Apple 归档 Web Clip 文档。Apple Touch 工具可准备 180px 不透明 PNG。不能把 PWA maskable 规则写成原生 iOS 资产要求。

Windows 和 macOS

在实际浏览器中安装，查看桌面、任务栏或 Dock 图标；这些位置不一定采用 Android 的裁切方式。提供 manifest 图标也不代表现代网站都要加入旧的 msapplication-* 磁贴声明。

最佳实践清单

保留可编辑源图，查看最小输出，逐一核对 manifest 引用，检查圆形叠加层，再在目标设备上安装测试。区分标准和 maskable 图稿，在同次发布中更新声明与文件。这些步骤有助于确认实现，不构成所有平台安装或显示结果的保证。

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

Maskable 图标是按启动器裁切准备的图稿。应让重要部分位于圆形安全区内，并检查目标设备；是否出现外框与实际浏览器、图稿和启动器有关。

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

any 用于标准图稿，maskable 用于按遮罩裁切准备的图稿。分别提供文件属于设计建议，不是必须把两种用途禁止写在同一项中的语法规则。

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

在不破坏细线与文字的前提下优化，并测量目标网络中的实际传输。不存在所有图标通用的 100 KB 上限；pngquant 等量化处理也不等于无损压缩。

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

Maskable 图稿建议采用明确的不透明背景，避免裁切后的意外填色；标准 any 图稿是否透明应根据实际设计决定，不能把透明度写成统一强制要求。

常见问题

下列回答区分浏览器安装推广条件、manifest 语法与图稿设计建议。

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

本工作流可从 192×192、512×512 PNG 开始。Chrome 安装推广条件列出这两个尺寸，但 manifest 规范没有对所有浏览器和手动安装路径统一规定这对尺寸。需要时另做 maskable 图稿。

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

Chrome 安装推广条件列出 192px 与 512px，同时保留是实用基线；不能笼统宣称单张 512px 一定通过检查，也不能把两张图片视为完整可安装 PWA。

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

purpose: "any maskable" 语法合法。只有同一图稿在有遮罩和无遮罩时都适用才合并；独立文件可分别控制构图与留白。

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

记录诊断原文和浏览器版本，核对 purpose: "maskable"、真实图片网址和安全圆内的图稿。只补字段不能证明图稿正确；某个 Lighthouse 审计项不保证存在于所有版本。

PWA 图标可以用 SVG 格式吗？

取决于浏览器和展示位置。对需要位图的目标保留 PNG，并在实际安装流程测试 SVG；普通页面能显示 SVG，不能证明启动器图标同样支持。

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

先检查实际启动页加载的 manifest、每张图片的响应、尺寸、子路径、重定向与登录要求，再检查浏览器安装条件和缓存／已安装状态。不能把所有问题都归因于未使用 Chrome。

相关工具

几何与 purpose 语义参考 Web App Manifest 规范；web.dev maskable 指南说明独立图稿与 DevTools 检查。原生 Android 自适应资源使用不同工作流，参阅 Android Adaptive Icons。内容纠错可通过关于与联系反馈。