什么是 maskable 图标
有人安装网页应用时，启动器会按自己的形状显示它的图标：有的手机是圆形，有的是圆角方形或水滴形。透明背景的普通图标如何放进这个形状，由平台决定。maskable（可遮罩）图标是专为裁切设计的：它用自己的背景铺满整个正方形，所以无论启动器裁出什么形状，得到的都是一个完整、有颜色的图标。
web app manifest 用每个图标的 purpose 成员来区分两者。W3C 规范列出了三种用途：any、maskable 和 monochrome；没有 purpose 的图标视为 any。
安全区：半径 40% 的圆
规范定义了图稿不会被任何遮罩裁掉的区域：“以图标中心为圆心、半径为图标尺寸 2/5（40%）的圆”。在 512 px 的图标上，这是一个居中、直径 410 px 的圆。MDN 把同一区域描述为直径等于图标尺寸 80% 的圆；web.dev 则提醒，外缘每边大约 10% 的部分可能会被裁掉。
图中是下方示例包里的 maskable 图标。第一个副本上画出了安全区；另外三个是同一个文件分别套上圆形、圆角方形和水滴形遮罩的效果。因为标志始终在圆内，每种遮罩都能让它保持完整，改变形状的只有背景。
Favicon 和 PWA 图标生成器 会把图稿本身（而不是它的边界框）放进这个圆内，再减去你选择的内边距。所以圆形标志几乎可以填满整个安全区，而方形照片会显得更小，因为它的四个角也必须放进圆内。
purpose 用 any 还是 maskable：为什么要两个文件
一个图标可以声明 "purpose": "any maskable"，web.dev 的 manifest 文章就用了这种写法。但 web.dev 自己关于 maskable 图标的文章却不建议这样做：为遮罩而加了留白的图标，在不加遮罩显示的地方会显得太小。来源之间说法不一，而用两个文件就能避免这种取舍。any 图标保持透明，图稿填满正方形；maskable 图标有满版背景，图稿放在安全区内。
| 用途 | 背景 | 图稿 | 显示位置 |
|---|---|---|---|
any |
透明 | 填满正方形，减去内边距 | 所有不裁切图标的地方 |
maskable |
你的背景色，铺满边缘 | 在 40% 的圆内 | 会把图标裁成某种形状的启动器 |
同时包含两种图标的 manifest
下面是示例包中的 site.webmanifest。图标路径是相对路径：规范规定 src 和 start_url 一样，相对于 manifest 自身的 URL 解析，所以只要图标与 manifest 放在一起，放在哪个文件夹都能用。
{
"name": "png2svg.art",
"short_name": "png2svg",
"icons": [
{
"src": "icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "icon-maskable-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "maskable"
},
{
"src": "icon-maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
],
"theme_color": "#0a2d8f",
"background_color": "#e8efff",
"display": "standalone",
"start_url": "/"
}
在每个页面中用 <link rel="manifest" href="/site.webmanifest"> 链接它。规范指定 .webmanifest 为注册的文件扩展名，并建议以 application/manifest+json 类型提供，不过任何 JSON 类型都可以接受。
这些尺寸并不是随便定的。MDN 的可安装性指南（2026 年 9 月更新）指出，除其他条件外，Chromium 系浏览器只会在以下情况下安装网页应用：manifest 中有 name 或 short_name、start_url、display 模式以及 192 和 512 px 的图标，并且网站通过 HTTPS 提供。Safari 的做法不同：WebKit 团队在介绍 Safari 26 时写道，安装没有任何门槛，网站定义了 manifest 图标时就会使用它们。MDN 还建议从至少 1024 px 见方的图稿开始；把小位图放大到 512 px，并不会增加细节。
如何测试 maskable 图标
在 Chrome 中打开开发者工具，进入 Application → Manifest（应用 → 清单），勾选 Show only the minimum safe area for maskable icons（仅显示 maskable 图标的最小安全区域）。这时图标部分会显示每个 maskable 图标被裁到安全区后的样子：如果有重要内容不见了，启动器也可能会把它裁掉。Chrome 的文档介绍了这个选项。web.dev 还推荐了 Maskable.app，这是一个第三方网站，可以预览图标在多种遮罩下的效果。最后一步检查，是在真实手机上安装应用看看。
可下载的真实示例
上面的图标来自用 favicon 生成器对本站自己的标志（一个已提交到代码库的 SVG，不是任何人上传的文件）运行的一次结果，内边距 8%，背景色 #e8efff。这些正是工具生成的文件。下载示例包（ZIP），即可查看每个文件及其 README。关于同一个文件包中浏览器标签页图标的部分，请阅读 SVG、PNG 还是 ICO：favicon 格式怎么选。