跳转到内容

Manifest 中的清单成员

start_url 清单成员

发布于 更新于

有限可用不支持的浏览器: Firefox (Desktop)W3C

清单成员 start_url 指定用户点击图标时已安装应用打开的 URL,让你单独设置启动页,不受安装时所在页面影响。 它相对清单 URL 解析,必须与链接该清单的文档同源;声明的 scope 若不包含它,这个 scope 会被忽略。没有 id 时,浏览器还用它确定应用身份。

提供安装入口的引擎会读取它:Chrome 39、Edge 79、Samsung Internet 4.0、Android 上的 Firefox 79、 iOS 上的 Safari 11.3 与 macOS 上的 Safari 17(BCD manifests.webapp.start_url)。Chromium 还把有效的 start_url 作为可安装性的必要条件。

属性 值
类型 字符串,按相对清单 URL 的 URL 解析。
默认值 链接该清单的文档 URL。Chromium 丢弃跨源值时也回退到该文档 URL,并提示 property 'start_url' ignored, should be same origin as document.(manifest_parser.cc)。
示例值 "/app/?utm_source=homescreen"。

如果 start_url 不在声明的 scope 内,Chromium 保留 start_url 而丢弃 scope,记录 property 'scope' ignored. Start url should be within scope of scope URL., 应用随即静默得到默认作用域(去掉文件名、查询串和片段的启动 URL)。另外,处理后的 id 默认取去掉片段的 start_url(查询串保留),所以在从未设置 id 的应用上改动 start_url 的路径,清单的身份就变了, 浏览器会把它当作新的 PWA,已安装的那个不会被更新(Chrome for Developers,“Uniquely identify PWAs with the web app manifest id property”)。

启动 URL 提供默认入口。通知点击、shortcuts、share_target 和 file_handlers 都可能打开作用域内的其他 URL,所以这些路由也应该支持冷启动。

示例使用同一份由 https://app.example/manifest.webmanifest 提供的清单。

解析到同一启动页的相对与绝对写法

链接到“解析到同一启动页的相对与绝对写法”一节

相对值相对清单 URL 解析,而不是相对链接它的页面。位于 /manifest.webmanifest 的清单写 "start_url": "app/",启动的是 https://app.example/app/,与绝对写法相同。

{
"start_url": "app/",
"scope": "/app/"
}

绝对写法 "https://app.example/app/" 与之等价。浏览器会丢弃 "https://cdn.example/app/" 等跨源值, 改用文档 URL。

给启动打分析标记并在启动时读取

链接到“给启动打分析标记并在启动时读取”一节

没有专用 API 时,start_url 上的查询串是区分已安装应用启动与浏览器访问的简便办法,不过任何人也可以在标签页里打开带标记的 URL。脚本读一次参数、 上报,然后把它从地址里删掉,刷新或复制链接就不会再算成一次启动;参数不存在时什么也不发。

{
"start_url": "/app/?utm_source=homescreen&utm_medium=pwa"
}
const params = new URLSearchParams(location.search);
if (params.get('utm_source') === 'homescreen') {
navigator.sendBeacon('/analytics', JSON.stringify({ launch: 'installed-app' }));
params.delete('utm_source');
params.delete('utm_medium');
history.replaceState(history.state, '', `${location.pathname}${params.size ? `?${params}` : ''}`);
}

start_url 变化(包括查询串)是让 Chrome 把新清单排入更新队列的条件之一(web.dev,“How Chrome handles updates to the web app manifest”)。清单 24 小时内没检查过时,启动时会触发检查;桌面版 Chrome 在应用的所有窗口关闭后才安装更新, 而且 start_url 的变化要求设置了 id。

迁移启动页而不产生第二个安装

链接到“迁移启动页而不产生第二个安装”一节

在已上线应用上改动 start_url 之前,先把 id 固定为浏览器已经推导出的值,也就是 DevTools 里的 Computed App Id(去掉片段的旧 start_url,查询串保留)。 有了 id,新的 start_url 作为更新应用;没有它,Chromium 会把清单当作另一个应用。这里旧的 start_url 是 /app/。

{
"id": "/app/",
"start_url": "/app/home/?utm_source=homescreen",
"scope": "/app/"
}

id 一旦设定,只要源不变,start_url 就可以随意改动(Chrome for Developers)。

规范

规范状态
Web 应用清单:start_urlW3C
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持39高来源1
Chrome (Android)#支持39高来源23
Edge (Desktop)#支持79高来源45
Firefox (Desktop)#不支持—高来源6
Firefox (Android)#支持79高来源—
Safari (macOS)#支持17高来源—
Safari (iOS)#支持11.3高来源—
Samsung Internet#支持4.0高来源78
WebView (Android)#支持39高来源910
  1. Web 应用可安装的前提是提供 `start_url`。
  2. Web 应用可安装的前提是提供 `start_url`。
  3. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  4. Web 应用可安装的前提是提供 `start_url`。
  5. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  6. browser-compat-data 未记录 Firefox 的支持。
  7. Web 应用可安装的前提是提供 `start_url`。
  8. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  9. Web 应用可安装的前提是提供 `start_url`。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/manifest-start-url.json · 全球使用占比: 94 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)