如果你曾经把一个网页应用添加到 Android 手机桌面，却发现原本精美的 Logo 被缩成了一个丑陋的小方块，嵌套在一个白色的圆圈里，那你就是遇到了所谓的“白框之耻”。这是因为 Android 使用了自适应图标机制，系统会根据用户设置的主题（圆角、圆形或方块）来裁剪图标。如果你没有提供 maskable icon favicon，系统为了保险起见，会强行给你的图标加一圈白边。
在 2026 年，用户对 PWA（渐进式 Web 应用）的期待是拥有原生应用般的体验。看看 Spotify 或 Slack，无论是在三星还是 Pixel 手机上，它们的图标都能完美填充整个形状。秘诀就在于 Web App Manifest 中的 maskable 属性。今天我们就来彻底解决这个问题。
准备工作：专业开发者的配置
在写代码之前，你需要一张高质量的源图。我强烈建议使用 512x512 像素的 PNG。虽然我们平时很推崇 SVG（可以参考我们的 SVG favicon 指南），但在 Android 的 manifest 配置中，PNG 的兼容性依然是最稳的。注意：这张图必须有实色背景，千万不要用透明背景，否则系统会自动填充颜色，效果往往很糟糕。
第一步：遵守 80% 安全区原则
这是新手最容易犯的错：把 Logo 画得太满。自适应图标本质上是一张“带出血位”的图片。系统会裁剪边缘以适应不同的形状。为了保证你的 Logo 不被“斩首”，必须把核心内容放在图像中间 80% 的安全区域内。简单来说，如果你的 Logo 能放进正中间的一个圆圈里，那就没问题了。
第二步：生成资源
你不需要手动去切五个尺寸。你可以使用 Mzu favicondl 来确保基础图标格式正确，但对于自适应图标，你需要在设计稿里预留足够的边距（我通常会在 Figma 里给 Logo 加上 10% 的背景色边距再导出）。如果你不确定现在的图标是否合格，可以查看我们的 图标审计指南。
第三步：更新 manifest.json
这是关键的一步。你需要告诉浏览器，这个图标是专门为裁剪设计的。如果没有 'purpose': 'maskable'，浏览器会把它当成普通图标处理。以下是 manifest.json 的标准写法：
{
'name': '我的专业应用',
'icons': [
{
'src': '/icons/icon-192x192.png',
'sizes': '192x192',
'type': 'image/png',
'purpose': 'any'
},
{
'src': '/icons/maskable-512x512.png',
'sizes': '512x512',
'type': 'image/png',
'purpose': 'maskable'
}
]
}注意 'purpose': 'any' 用于任务切换器等非裁剪场景，而 'maskable' 则是专供 Android 桌面使用的。如果你使用的是现代框架，我们的 Next.js 图标指南 也有相关的集成方法。
第四步：使用 DevTools 验证
不要盲目上线。在电脑端 Chrome 打开你的网站，按 F12 进入开发者工具，找到 Application 选项卡，点击左侧的 Manifest。向下滚动到图标部分，勾选 “Show only the minimum safe area for maskable icons”。如果你的 Logo 在那个圆圈里显示完整，那就大功告成了。
避坑指南
最常见的坑就是使用透明背景。当系统裁剪透明 PNG 时，背景往往会变成默认的灰色或白色，非常难看。务必使用符合品牌色的实色背景。另外，别忘了在 HTML 的 <head> 中引入 manifest：<link rel='manifest' href='/manifest.json'>。
配置自适应图标是区分“业余开发者”和“专业工程师”的小细节。它只需要花你十分钟时间，却能让你的品牌在数亿 Android 设备上看起来非常靠谱。如果你搞定了移动端，发现桌面端图标还是模糊不清，记得去 Mzu favicondl 生成一套标准图标来配套使用。