PWA manifest 清单要求：浏览器真正会检查的字段（2026）

浏览器判断你的站点能不能被安装，靠的就是一个很小的 JSON 文件。绝大多数"为什么没有安装按钮"的工单，最后都归到少了一个图标尺寸、或者 display 写成了浏览器会忽略的值——不是什么复杂问题。下面是 Chromium 当前真正会检查的清单、哪些是可选项、以及哪条是早已过时的说法。

必填字段

对 Chromium 系浏览器（Chrome、Edge、三星浏览器、Opera）来说，web app manifest 必须包含：

满足这五条的最小 manifest：

{
  "name": "Your App Name",
  "short_name": "YourApp",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    { "src": "/icons/192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "prefer_related_applications": false
}

还有两个条件不在文件里：

• 页面必须走 HTTPS，开发环境可以用 localhost / 127.0.0.1。测试域名用纯 HTTP 没有例外可开。
• 页面必须引用这个 manifest：<link rel="manifest" href="/manifest.webmanifest">，并且它要能被取到——放在登录态后面、或被 CORS 挡住，都会静默失败。

关于 Service Worker 的过时说法

流传最久的一条过时建议是：可安装必须要有带 fetch 处理的 service worker。这在早期 Chromium 版本成立，现在不成立。一个站点完全没有 service worker 也可以被安装。

这不代表 service worker 没用——离线能力、缓存、后台同步仍然靠它，但那和"能不能被安装"是两个目标。如果你当初加它只是为了解锁安装提示，这个理由已经消失；如果是为了让 App 在弱网下仍可用，这个理由依然成立。能力边界见我们这篇 PWA 离线支持。

非必填、但会改变用户看到什么的字段

这些不构成安装门槛，却决定了安装体验长什么样：

• screenshots + description——两者都提供时，Chromium 会展示更完整的安装弹窗，接近应用商店的样式；不提供就只有一行简陋提示。
• id——App 的稳定身份。不写就用 start_url 推导，日后改 start_url 会被当成另一个 App，而不是同一个 App 的更新。
• scope——哪些 URL 留在已安装窗口内。范围之外的链接会跳回浏览器标签页。
• theme_color / background_color——工具栏配色与启动图背景。不写 background_color，启动时会闪一下白屏。
• icons[].purpose: "maskable"——让 Android 把图标裁成系统形状而不留白边。它是在标准图标之外再加一份，不是替代。
• shortcuts——桌面图标长按出现的快捷入口。
• orientation、categories——按需，写上无害。

各浏览器支持并不一致

满足 Chromium 清单，不等于所有浏览器都以同样方式安装。

实际影响是：在 iOS 上安装是用户在分享菜单里的一次手动操作，所以你的引导必须明确告诉用户怎么点，没有可以程序化触发的提示。两端流程差异见添加到主屏幕提示的机制。

别猜，按这四步验

1. DevTools → Application → Manifest。 Chromium 会列出解析后的 manifest，缺什么会在可安装性一栏直接给出原因。
2. Lighthouse 的可安装性审计。 对线上 URL 跑，别对 localhost 跑——HTTPS 与响应头问题只在真实域名上才暴露。
3. 以匿名客户端取一次 manifest：curl -I https://你的站点/manifest.webmanifest，确认返回 200 且是 JSON 类型。返回的是 SPA 的 HTML 外壳，是最常见的静默失败。
4. 拿真机 Android 测一遍。 模拟器和桌面的安装行为，都与用户手里的手机不同。

看着没问题却装不上的常见原因

• 只声明了 512px 图标，或 sizes 字符串写错，导致 192px 这条不满足。
• display 写成 "browser"，等于明确放弃独立窗口。
• start_url 跳到登录页，或者根本不在 scope 范围内。
• 兜底路由把 manifest 以 Content-Type: text/html 返回。
• 站点还在 HTTP，或 HTTPS 证书设备不信任。
• prefer_related_applications 是 true——多半是模板里指向原生应用的残留。

如果你还在判断"可安装的网页应用"这条分发路线本身是否合适，与 APK 打包分发的取舍见 PWA 与 APK 对比，与 TWA 的区别见 PWA 与 TWA 对比。

常见问题

PWA 必须有 Service Worker 才能安装吗？

不必。当前 Chromium 的可安装性规则不要求 service worker。离线、缓存、后台能力仍然需要它，但那与可安装性是两件事。

到底必须提供哪些图标尺寸？

192px 和 512px 各一个。更多尺寸与 maskable 变体能提升 Android 上的图标质量，但不属于硬性要求。

PWA 能在 HTTP 下安装吗？

只有本地开发的 localhost / 127.0.0.1 可以。其他任何域名都必须是 HTTPS 且证书有效。

iPhone 上为什么没有安装提示？

iOS 不提供可程序化触发的安装提示。用户要从分享菜单添加——所有支持版本的 Safari，以及 iOS 16.4 及以后的 Chrome、Edge、Firefox、Orion。这一步必须由你的界面引导。

改了 start_url 会不会影响已安装的 App？

会。没有显式写 id 时，App 身份由 start_url 推导，改动之后浏览器会把它当成新 App 而不是原有安装的更新。尽早把 id 定下来。