---
title: "App Instance"
description: "单实例状态与窗口聚焦。"
---


> 查询当前进程是否为单实例主实例，并尝试把已有主窗口带到前台。

## 模块边界

`appInstance` 只负责单实例状态查询与窗口聚焦，不负责文件锁、配置文件合并或升级迁移。
单实例锁的持有方和释放时机由宿主负责。

| 方法 | 协议命令 | Windows | Android |
| --- | --- | --- | --- |
| `KSM.appInstance.state()` | `app.singleInstance.state` | 支持 | 支持 |
| `KSM.appInstance.focus()` | `app.singleInstance.focus` | 支持 | 支持 |

## 返回值

`app.singleInstance.state` 返回 `{ primary: boolean }`。`primary` 表示当前实例是否
是允许继续运行的主实例；非主实例应尽快退出，不要继续启动第二个主进程。

`app.singleInstance.focus` 返回 `{ focused: boolean }`。`focused` 表示宿主是否成功
把主窗口带到前台。

## 示例

```ts
import { KSM } from 'kasumi-bridge';

const { primary } = await KSM.appInstance.state();
if (!primary) {
  await KSM.appInstance.focus();
  window.close();
}
```

## 错误与边界

- 宿主未注入单实例实现时，`state` 默认返回 `primary: true`，不主动阻止第二进程。
- 真正的互斥锁必须由原生进程边界实现，不能依赖前端返回值。
- `focus` 只做“请求前台”操作，由操作系统窗口规则决定是否成功。

## 排查

| 现象 | 优先检查 |
| --- | --- |
| 第二个实例仍能启动 | Windows 互斥量 / Android `FLAG_ACTIVITY_SINGLE_TOP` 是否实现 |
| `focus` 返回 `false` | 窗口句柄是否仍然有效，是否被系统置为不可前台 |