manifest: launch_handler 支持情况

manifest: launch_handler — launch_handler 成员的 client_mode 子字段控制已安装 PWA 的启动方式：是复用已有的应用窗口，还是打开一个新窗口，以及该窗口是否会被导航到本次 启动的目标 URL。

浏览器与生态支持

• 图例
• 支持
• 部分支持
• 需开启标志
• 不支持
• 未知

浏览器 / 平台	支持	版本	置信度	来源	备注
Chrome (Desktop)	支持	110	高	来源	—
Chrome (Android)	支持	110	高	来源	1
Edge (Desktop)	支持	110	高	来源	2
Firefox (Desktop)	不支持	—	高	来源	3
Firefox (Android)	不支持	—	高	来源	45
Safari (macOS)	不支持	—	高	来源	6
Safari (iOS)	不支持	—	高	来源	78
Samsung Internet	支持	21.0	高	来源	9
WebView (Android)	支持	110	高	来源	10

1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
3. browser-compat-data 未记录 Firefox 的支持。
4. browser-compat-data 未记录 Firefox for Android 的支持。
5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
6. browser-compat-data 未记录 Safari 的支持。
7. browser-compat-data 未记录 iOS 版 Safari 的支持。
8. 由 browser-compat-data 镜像自 Safari 的数据推导。
9. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/manifest-launch-handler.json · 全球使用占比: 72 % (StatCounter 2026-05)

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

设置 client_mode

根据 Chrome for Developers 的说明，launch_handler 只有一个子字段 client_mode， 未指定时默认值为 {"client_mode": "auto"}：

{
  "launch_handler": {
    "client_mode": "navigate-new"
  }
}

根据 MDN 的说明，client_mode 允许的取值为：navigate-new（始终打开一个新的客户端）、 navigate-existing（聚焦并导航已有的客户端，若没有已打开的客户端则回退为 navigate-new）、focus-existing（聚焦已有客户端但不对其导航，同样在没有已打开客户端 时回退为 navigate-new），以及 auto（由用户代理根据平台自行选择合适的行为）。

通过 LaunchQueue 读取启动目标

根据 MDN 的说明，无论使用哪种 client_mode，本次启动的目标 URL 都会通过 window.launchQueue 提供，以便实现自定义的导航处理：

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const url = new URL(launchParams.targetURL);
      // 自行将已打开的应用窗口路由到被启动的 URL。
      history.pushState(null, "", url.pathname + url.search);
    }
  });
}

运行时检测与回退

在注册 consumer 之前先检测 "launchQueue" in window。当 launchQueue 不可用时， 下方的回退方案会根据页面当前的 location 进行路由：

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      route(new URL(launchParams.targetURL));
    }
  });
} else {
  // LaunchQueue 不可用——回退到当前页面的 URL。
  route(new URL(location.href));
}

常见问题

• 根据上方的兼容性数据，Firefox 与 Safari 均未实现 launch_handler——请始终提供一个 仅依赖 location 即可工作的回退方案。
• 根据 MDN 的说明，当没有已打开的客户端时，navigate-existing 与 focus-existing 都会回退为 navigate-new 的行为——不要假设一定存在已打开的窗口。
• 在调用 setConsumer() 之前先检测 "launchQueue" in window。
• navigate-new 与 navigate-existing 会将客户端导航到目标 URL； focus-existing 不会这样做，因此如果该模式下聚焦的客户端也应路由到目标，请处理 launchParams.targetURL。

下一步

• manifest: file_handlers 支持情况 —— 另一个 通过 window.launchQueue 传递启动数据的 manifest 成员。
• manifest: share_target 支持情况 —— 一个 相关的、用于处理启动时传入数据的 manifest 成员。

← 返回兼容性浏览器。