Web App Manifest 怎么配置？哪些属性影响 PWA 安装体验？
Web App Manifest 是 PWA 的应用说明书。浏览器会读取这个 JSON 文件，决定应用能不能被安装、安装后叫什么名字、从哪个地址启动、图标长什么样、打开时像浏览器标签页还是独立应用。它本身不负责离线缓存，离线能力要靠 Service Worker；Manifest 解决的是“这个 Web 应用能不能像 App 一样出现在设备上”。
一个可用的 Manifest 示例
Manifest 通常放在站点根目录，并在 HTML 里引用。最小可用配置不复杂，但图标、start_url、scope、display 这些字段会直接影响安装体验。
<link rel="manifest" href="/manifest.webmanifest"> <meta name="theme-color" content="#0f172a">
{ "name": "Levenx Tools", "short_name": "Tools", "description": "常用开发工具集合", "start_url": "/?source=pwa", "scope": "/", "display": "standalone", "background_color": "#ffffff", "theme_color": "#0f172a", "lang": "zh-CN", "icons": [ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" } ] }
关键属性分别管什么
name 是完整应用名，常出现在安装弹窗里；short_name 用在主屏幕图标下方，太长会被截断。start_url 决定用户从桌面图标打开时进入哪个页面，常用来加来源参数，但不能写成需要登录态才能访问的临时地址。scope 控制应用边界，超出边界的链接会回到浏览器里打开。
display 决定窗口形态。多数业务应用选择 standalone，看起来像独立 App；内容型网站可以保留 browser，减少用户迷路。fullscreen 更适合游戏、展厅或沉浸式页面，不适合需要地址栏安全感的交易类场景。
图标是最容易被忽略的部分。Android 更依赖 192 和 512 尺寸，maskable 图标能适配圆形、圆角矩形等不同启动器。踩坑点是把普通图标直接声明成 maskable，结果边缘被裁掉，桌面上看起来像被剪了一块。
安装体验还受哪些因素影响
Manifest 写得完整，不代表用户一定愿意安装。应用首屏速度、离线回退、登录后入口是否稳定，都会影响安装后的真实体验。start_url 如果带了活动参数，活动结束后可能打开废弃页面；图标如果没有透明边距，在部分启动器上会显得很廉价。更稳的做法是把 Manifest 当成产品入口配置，而不是前端构建时顺手生成的文件。团队还要约定图标和主题色的更新流程，因为这些内容在已安装应用里刷新并不及时。多语言站点最好按语言提供合适的 name、description 和截图，否则安装弹窗里出现混合语言，会让用户怀疑应用是否正规。
调试 Manifest
Chrome DevTools 的 Application 面板能看到 Manifest 解析结果、图标预览和安装条件。安装失败时先看控制台警告，再检查 HTTPS、Service Worker、图标尺寸、start_url 是否可访问。iOS Safari 对 Manifest 支持不完整，仍然会受 apple-touch-icon、apple-mobile-web-app-capable 等标签影响，所以移动端不要只测 Chrome。
追问
Manifest 配好了就一定会出现安装提示吗？
不一定，Manifest 只是必要条件之一。浏览器还会看 HTTPS、Service Worker、访问频率、图标和页面可用性等条件。不同浏览器的安装入口也不一样，有些不会主动弹提示，只在菜单里提供安装。取舍上不要把业务转化完全压在自动弹窗上，页面内最好有自己的安装引导。
start_url 和 scope 有什么区别？
start_url 是从桌面图标启动时打开的入口，scope 是 PWA 能控制的路径范围。比如 start_url 是 /app，scope 是 /，用户仍然可以在独立窗口里访问站内其他路径。如果 scope 设得太窄，点到详情页可能突然跳回浏览器。这个坑在多目录站点里很常见，发布前要从安装入口完整走一遍。
display 应该选 standalone 还是 fullscreen？
大多数 PWA 选 standalone 更稳，因为它去掉浏览器地址栏，但保留系统级窗口语义。fullscreen 会让应用占满屏幕，适合游戏和大屏展示，但用户可能不知道如何返回或确认当前页面来源。交易、登录、内容阅读类应用不建议轻易全屏。这里的取舍是沉浸感和可控感，越沉浸越要自己补导航。
图标为什么要配置 maskable？
不同 Android 启动器会把图标裁成不同形状，maskable 图标能给系统预留安全区域。普通正方形图标如果被强行裁切，Logo 可能贴边或缺角。边界是并非所有平台都使用 maskable，但配置好不会影响普通图标。实际制作时要把主体放在中心安全区，别把文字和品牌符号贴到边缘。
Manifest 更新为什么有时不生效？
Manifest 会被浏览器缓存，桌面已安装应用也不会每次都立刻刷新元数据。改了图标或名称后，可能需要重新安装、清缓存或等待浏览器更新。不要频繁改 start_url 和应用名，这会让用户和统计数据都变得混乱。线上调整时先在测试域名验证，再逐步发布到正式环境。