跳转到内容

Manifest 中的概念

已安装的 PWA 如何获取清单更新

发布于 更新于

已安装的 PWA 保留一份安装时所用清单的本地副本。Chrome 按计划重新抓取线上清单,与这份副本比较, 并且只在应用的所有窗口都关闭之后才应用变化。桌面 Chrome 和 Android Chrome 用来触发更新的字段不同,更新时应用的字段也不同。桌面端无法更新图标。

Chrome 团队在 web.dev 的 How Chrome handles updates to the web app manifest 中记载了更新行为。Edge 154 使用 Chromium,共用桌面端更新机制。Apple 没有为 Safari 27 主屏幕应用或 Dock 应用发布对应说明;Firefox 157 不从清单安装 Web 应用,因此这两种情况下的更新行为没有结论。

已安装应用的每次启动,以及在浏览器标签页里对站点的每次访问,都会让 Chrome 检查上一次比较清单的 时间。如果那是在浏览器上次启动之前,或者已经超过 24 小时,Chrome 就重新抓取清单。抓回的值与 本地相同时,计时器重置,不发生别的事。

在桌面端,name、short_name、display、scope、shortcuts、start_url、theme_color、 file_handlers 中任何一项发生变化都会把新清单排入队列;应用的每个窗口都关闭后安装新清单,然后 应用除 icons 以外的所有字段,桌面 Chrome 不更新图标。要更新 start_url,清单必须声明 id,因为没有 id 时旧的 start_url 就是应用的身份;display 从 browser 改为 standalone 不会改变那些选择在标签页中打开应用的用户,用户的窗口偏好优先于 清单。

在 Android 上同样每 24 小时检查一次,但触发列表是 name、short_name、icons、 background_color、display、orientation、scope、shortcuts、start_url、theme_color 与 share_target,而应用变化意味着向 Google 的铸造服务器请求一个新的 WebAPK。Chrome 会等到 应用关闭、设备在充电且连接 Wi-Fi 之后才去请求;新 WebAPK 安装后,包括图标在内的每个字段都是 最新的。服务器不可达时 Chrome 会退避,最慢每 30 天检查一次。

重命名或移动清单文件会切断这条链:Chrome 重新抓取的是安装时的那个 URL,那里返回 404 就意味着 永远发现不了更新。保持清单 URL 稳定,只改它的内容。

前两个示例是清单改动及其对已安装用户的影响;第三个是如何不等一天就看到结果。

迁移启动 URL 而不产生第二个应用

链接到“迁移启动 URL 而不产生第二个应用”一节

团队把应用从 / 迁到 /app/。因为清单声明了 id,Chrome 把改过的清单视为同一个应用,在下一次 检查后应用新的 start_url;没有 id 的话,这个改动在桌面端会被忽略,已安装应用仍然启动 /。

{
"id": "/",
"name": "Ledger",
"start_url": "/app/?source=installed",
"scope": "/",
"display": "standalone"
}

迁移前先单独发布一次,只添加 id。等已安装的副本带上这个 id,浏览器才能识别后续的 start_url 变化。

更换主题色并知道用户何时能看到

链接到“更换主题色并知道用户何时能看到”一节

theme_color 在两份触发列表上都有,所以品牌换色无需重装就能到达已安装用户。部署之后,用户还要等浏览器按计划检查更新。

{
"name": "Ledger",
"theme_color": "#0b5fff",
"background_color": "#ffffff"
}

整天开着应用的桌面用户,要等某次检查发现变化、再关闭最后一个窗口之后才看到新颜色;Android 用户还需要充电加 Wi-Fi 才能让 WebAPK 重新铸造。预期是一两天,很少在 Wi-Fi 下充电的设备更久。

Chrome 为开发者提供两条绕过 24 小时节流的路径:重启浏览器(about://restart 会重置计时器), 或带 --disable-manifest-update-throttle 启动。脚本在应用内抓取清单,与预先写入已安装 start_url 的版本戳比较,判断已安装副本是否仍是旧版。

async function installedManifestIsStale() {
const installedVersion = new URL(location.href).searchParams.get('v'); // 来自 start_url
const live = await fetch('/manifest.webmanifest', { cache: 'no-store' }).then((r) => r.json());
const liveVersion = new URL(live.start_url, location.origin).searchParams.get('v');
if (!installedVersion || !liveVersion) return false; // 没有版本戳:无可比较
return installedVersion !== liveVersion;
}

页面无法读取浏览器保存的清单副本,只能从 start_url 里的版本戳观察已安装清单。因此测试时常在 start_url 中添加 ?v=。

规范

规范状态
Web Application Manifest: id memberW3C