如何通过HTML的Launch Handler的client_mode控制已有PWA窗口的复用行为-html教程-PHP中文网

client_mode 是 web app manifest 中 launch_handler 的可选字段，用于提示浏览器复用已有 pwa 窗口而非新建，支持 "focus-only" 和 "navigate-existing" 两种值，但非强制，实际行为受浏览器版本、scope 匹配、display 模式等影响。

如何通过html的launch handler的client_mode控制已有pwa窗口的复用行为

client_mode 是什么，它真能复用已有 PWA 窗口？

client_mode 是 Web App Manifest 中 launch_handler 的一个可选字段，用于告诉浏览器：当用户再次启动 PWA（比如从桌面图标、系统启动器或通知点击）时，是否尝试复用已打开的客户端（即已有窗口/标签页），而不是总新建一个。但它**不是强制复用开关**，而是提供策略提示——实际行为受浏览器实现、当前会话状态、scope 路径匹配、以及是否启用了 display: 'standalone' 或 'minimal-ui' 等因素共同影响。

如何正确配置 launch_handler.client_mode

必须在 Web App Manifest（通常是 manifest.json）中声明，且仅在支持该字段的浏览器（Chrome 124+、Edge 124+）中生效。常见有效值只有两个字符串：

"focus-only"：只聚焦已有匹配窗口，不导航；若无匹配窗口，则新建
"navigate-existing"：聚焦已有窗口，并将其 location 导航到本次启动的 URL（即 start_url 或 deep link）

错误写法包括："reuse"、true、"auto" —— 这些会被忽略，退化为默认行为（通常新建窗口）。示例正确配置：

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

为什么写了 client_mode 却没复用？常见断点

即使配置正确，复用也常失败。关键排查点：

html-ppt-to-pdf

将使用 `

` 约定的 HTML 幻灯片转换为高保真、矢量文本 PDF（使用 Playwright + Chromium 原生 PDF 功能）。

下载

浏览器版本不足：确认 Chrome ≥ 124，且未启用 #enable-experimental-web-platform-features 以外的实验性标志（新版已默认开启）
start_url 和现有窗口 URL 不在同一 scope 内：复用只发生在同 scope 下的 clients；若你从 /app 启动但已有窗口在 /admin，且 manifest scope 是 "/app"，则不会复用
已有窗口被用户手动关闭了 service worker 上下文：比如用户强制刷新（Ctrl+F5）、或关闭了所有 tab 后又重新打开一个非 PWA 标签，可能导致 SW 失活，此时新启动无法关联旧 client
使用了 display: 'browser'：该模式下浏览器通常禁用复用逻辑，强制走普通标签页流程

如何验证 client_mode 是否生效？

最直接方式是监听 navigation 类型的 beforeinstallprompt 事件（不推荐）或更可靠的运行时检测：

在 PWA 页面中加一段调试代码，检查 navigator.launchQueue 是否存在，以及 self.clients.matchAll() 返回的 clients 数量和 URL

启动后立即执行：

self.addEventListener('activate', () => {
  self.clients.matchAll().then(clients => {
    console.log('Active clients:', clients.map(c => c.url));
  });
});