# Manifest launch_handler：控制已安装应用的启动方式

> launch_handler 清单字段的 client_mode 如何控制启动已安装 web 应用时是聚焦或导航已有窗口、还是打开新窗口，它的四个取值、回退行为，以及当前实验性、非 Baseline 的浏览器支持状况。

**一句话：** `launch_handler` 定义了一个 `client_mode`，用来告诉浏览器启动已安装应用时，应该聚焦或
导航一个已有的应用窗口，还是打开一个新窗口。

## 语法

```json
{
  "launch_handler": {
    "client_mode": "focus-existing"
  }
}
```

`client_mode` 也接受一个字符串数组；数组中第一个有效值会被使用：

```json
{
  "launch_handler": {
    "client_mode": ["focus-existing", "auto"]
  }
}
```

## `client_mode` 取值

| 值 | 含义 |
|---|---|
| `auto` | 用户代理根据平台自行决定合适的加载上下文（例如在移动端 `navigate-existing` 可能更合理，在桌面端 `navigate-new` 可能更合理）。当提供的所有取值均无效时，也会回退到这个默认值。 |
| `focus-existing` | 如果应用已经在某个 web 应用客户端中加载，该实例会被聚焦，但不会导航到启动目标 URL。目标 URL 会通过 `Window.launchQueue` 提供，供自定义导航处理使用。 |
| `navigate-existing` | 如果应用已经加载，已有客户端会被聚焦**并**导航到启动目标 URL。目标 URL 同样会通过 `Window.launchQueue` 暴露。 |
| `navigate-new` | 应用会在一个新的 web 应用客户端实例中加载。目标 URL 会通过 `Window.launchQueue` 提供。 |

## 回退行为

- 如果某个 `client_mode` 字符串（或数组中所有取值）无效，行为会回退到 `auto`。
- 当没有已加载的现有应用实例时，`focus-existing` 与 `navigate-existing` 都会回退到 `navigate-new` 的行为。

## 浏览器支持

`launch_handler` 被标记为实验性特性，可用性有限——它在一些广泛使用的浏览器中尚不可用，也不属于
Baseline。在生产环境中依赖它之前，请查看当前的浏览器兼容性数据。

## 实用清单

- [ ] 根据应用在已打开状态下再次被启动时应有的行为，选择合适的 `client_mode`（或回退数组）。
- [ ] 在所有会暴露目标 URL 的模式中，从 `Window.launchQueue` 读取该 URL。
- [ ] 在生产环境中依赖非 `auto` 行为之前，先做特性检测并核实当前浏览器支持情况。

## 相关参考

- [Manifest start_url](/zh/reference/manifest/start-url/) — 另一个会影响已安装应用打开哪个 URL 的清单字段