Web App Manifest(manifest.json)验证工具

只需粘贴manifest.json的内容,即可检查是否满足PWA的安装条件。自动检查name、start_url、display、icons等必填项以及maskable图标的有无,并以列表形式显示存在的问题。

Tips

  • 建议同时设置name和short_name。如果没有short_name,主屏幕图标下方显示的文字会由name机械截断而来,有时会出现不符合预期的显示效果。
  • 如果没有设置purpose: "maskable"的图标,在部分Android设备上,图标周围可能会被不自然地裁切,或者透出背景色。只需在现有的icons数组中新增一条maskable用的条目即可解决。
  • icons中请至少提供一个192x192以上尺寸的图标,如有可能,也请准备一个512x512以上尺寸的图标。前者用于主屏幕图标,后者用于启动画面(splash screen)的显示。
  • Chrome等浏览器实际采用的PWA安装条件今后可能会发生变化,因此本工具的判定结果仅供参考,建议最终还是通过Chrome DevTools的Application面板等进行确认。
  • start_url使用相对路径(例如“/?source=pwa”)也没有问题。如果想统计安装来源,可以附加查询参数,这样在访问分析中更容易区分通过PWA启动的访问。

常见问题

在主流浏览器的PWA安装条件中,通常需要具备name或short_name中的一个、start_url、display(fullscreen、standalone、minimal-ui、browser中的一个),以及包含192x192以上尺寸的icons数组。只要缺少其中任何一项,就有可能不会显示安装提示。

指的是设置了purpose: "maskable"的图标。Android设备会将主屏幕图标裁切(遮罩)成圆形或圆角矩形等形状显示,如果直接对普通图标图像做这种遮罩处理,图案边缘有时会被裁掉。maskable图标通过在中央预留空白(安全区域)进行设计,无论被裁切成什么形状都能保持美观显示。

请使用宽和高之间用x分隔的格式指定,例如“192x192”。如果一个图标文件(例如SVG)适用于任意尺寸,也可以指定为“any”。如果想用一个条目表示多个尺寸,也可以用空格分隔并列写出,例如“192x192 512x512”。

根据W3C规范,共定义了四种值:fullscreen(占用整个屏幕)、standalone(隐藏浏览器界面、呈现应用般的外观)、minimal-ui(显示最小限度的浏览器界面)、browser(作为普通浏览器标签页打开)。如果想要呈现PWA的外观,通常会指定为standalone。

本工具仅对manifest.json的内容是否符合规范进行静态检查。实际能否安装还与是否通过HTTPS提供服务、Service Worker是否正确注册等其他条件有关,因此最终请务必同时通过浏览器的开发者工具或实机进行确认。
ツールくん

闲话 ― Web App Manifest与PWA的关系

Web App Manifest是由W3C制定的JSON格式规范,用于统一声明将网站添加到主屏幕并像原生应用一样安装所需的信息(应用名称、图标、启动时的显示模式、主题色等)。PWA(Progressive Web App)这个词本身是2015年由Google的工程师提出的概念,而构成其核心的技术要素之一,正是这个manifest.json,以及负责离线运行的Service Worker这两者。

如果manifest.json没有正确配置,浏览器就不会将其识别为“可安装的应用”,也就不会显示提示添加到主屏幕的弹窗(例如Chrome的“安装”横幅)。尤其是icons分辨率不足或display值错误这类问题,由于JSON本身在语法上仍然正确,很难被察觉,往往要等到实际尝试安装时才会发现。

maskable图标(purpose: "maskable")是一个相对较新的规范,大约从2019年起为了支持Android的“自适应图标”而新增。普通图标会根据设备被裁切成圆形、圆角矩形等形状,如果准备的图标图像没有留白,图案的一部分就可能被裁掉。maskable用的图标需要设计时考虑安全区域(safe zone),通常会与普通的icons条目分开单独准备。

本工具专注于对manifest.json本身进行静态验证,并不检查Service Worker的注册状态、是否通过HTTPS提供服务等其他会影响实际能否安装的条件。建议在生产环境中进行最终确认时,同时使用浏览器的开发者工具(例如Chrome DevTools的Application面板)加以核实。