---
title: "应用配置"
description: "用精简配置管理 Windows 与 Android 的包名、版本和构建注入。"
---


> 用一份精简配置管理 Windows 与 Android 的包名和版本，并让 CLI、原生构建和运行时信息保持一致。

## 模块边界

应用配置入口是仓库根目录 `kasumi.conf.json`。当前只包含 Windows 与 Android 各自的
`packageName` 和 `version`，不承载窗口、图标、权限、CSP 或资源路径配置。

JSON Schema 位于 `protocol/kasumi.config.schema.json`。`pnpm ksm build`、`test`、
`package` 和 `dev` 默认读取根配置，也可以使用 `--config <path>` 指定其他文件。

## 配置结构

```json
{
  "$schema": "./protocol/kasumi.config.schema.json",
  "windows": {
    "packageName": "kasumi-win32-example",
    "version": "0.1.0"
  },
  "android": {
    "packageName": "dev.kasumi.example",
    "version": "0.1.0"
  }
}
```

|平台 |字段 |作用 |
| --- | --- | --- |
| Windows | `packageName` | EXE 版本资源的内部名称与产品名称 |
| Windows | `version` | 文件版本、产品版本、示例 ZIP 文件名与 `app.getInfo.version` |
| Android | `packageName` | Gradle `applicationId` 与 `adb` 启停、卸载目标 |
| Android | `version` | Gradle `versionName` 与 `app.getInfo.version` |

`windows` 和 `android` 都是必填对象，不允许缺字段或附加未定义字段。

## 校验规则

|字段 |规则 |
| --- | --- |
| `windows.packageName` | 以字母或数字开头，只允许字母、数字、点、下划线和连字符 |
| `android.packageName` | 至少两段 Java 包名，每段以字母开头，只允许字母、数字和下划线 |
| `version` | 标准 SemVer，例如 `1.2.3`、`1.2.3-beta.1` |

配置缺失、JSON 语法错误、未知字段、非法包名或非法版本会让 CLI 在启动构建前直接失败，
不会把错误值传给 CMake 或 Gradle。

## 构建注入

Windows 构建把配置作为 CMake 缓存变量传入：

```powershell
pnpm ksm build --windows --target example
```

等价参数是 `-DKASUMI_APP_PACKAGE_NAME` 和 `-DKASUMI_APP_VERSION`。版本会写入生成
的 `app_version.rc`，并传给 `KSMWebView2Host` 与 `KSMWindowsHostServices`。

Android 构建把配置作为 Gradle 属性传入：

```bash
pnpm ksm build --android --target example
```

等价参数是 `-PksmPackageName` 和 `-PksmVersion`。示例通过
`BuildConfig.VERSION_NAME` 把版本传给 `KSMAndroidHostServices`。Gradle `namespace`
保持源码包不变，修改 `applicationId` 不会移动 Kotlin 源码目录。

## 自定义配置路径

```bash
pnpm ksm build --all --target example --config configs/staging.json
```

相对路径从仓库根目录解析。CI 可以为不同渠道准备独立配置文件，不需要修改
`build.gradle.kts` 或 `CMakeLists.txt`。

## 运行时读取

```ts
import { KSM } from '@kasumi/bridge';

const info = await KSM.app.getInfo();
console.info(info.version);
```

Windows 与 Android 的 `app.getInfo.version` 都来自当前平台配置。包名用于构建和宿主
定位，不作为前端可见的真实文件路径或设备标识。

## 排查路径

1. 构建前报配置错误：检查 `kasumi.conf.json` 是否为合法 JSON。
2. 报未知字段：删除当前版本未支持的配置项，避免把 Tauri 字段直接复制进来。
3. Android 包名报错：确认是至少两段反写域名，例如 `dev.kasumi.example`。
4. 版本报错：确认使用 `major.minor.patch`，预发布标识只能放在 `-` 后。
5. Windows 版本未变化：确认构建使用了同一份 `--config`，并重新生成 EXE。
6. Android 安装冲突：确认新的 `applicationId` 与设备上已有应用一致，或先卸载旧包。

## 相关

- [开发入口](/docs/kasumi/development)
- [Windows SDK](/docs/kasumi/api)
- [Android SDK](/docs/kasumi/api)