# bt-app 常见问题

## 为什么窗口打不开
先在项目目录运行：

```bash
./bt-app.exe run
```

查看控制台输出的应用名称、运行模式、入口文件和错误信息。当前目录如果既没有 `app.json`，也没有 `index.html`，会打开初始化引导页。

## 为什么 entry 加载失败
按模式检查：

- `static`：`entry` 必须是项目内相对文件，例如 `index.html`。
- `server`：`entry` 必须是 `http://` 或 `https://` 地址，且 `server.bt` 必须启动对应服务。
- `remote`：`entry` 必须是可访问的 `http://` 或 `https://` 地址。

`static` 入口不能写绝对路径，不能包含 `..`。

## 为什么图标没有生效
当前 `app.icon` 只支持项目内 `.ico` 文件：

```json
{
  "app": {
    "icon": "logo.ico"
  }
}
```

开发运行时如果图标不存在，会回退到内置图标。打包时如果图标文件不存在，会直接失败。

## 为什么任务栏图标和 exe 图标不一致
运行窗口图标由 WebView 窗口加载，打包 exe 图标由构建阶段写入 Windows PE 资源。请确认：

- `app.icon` 指向同一个 `.ico`。
- `resources` 或自动资源收集包含该图标。
- 已重新执行 `bt-app.exe build`。
- Windows 资源管理器可能缓存旧 exe 图标，可以换文件名或重启资源管理器后再看。

## 为什么端口被占用
`server` 模式会执行 `server.bt`。如果 `net.listen` 绑定端口被其他进程占用，服务启动失败，窗口会显示启动错误页。

处理方式：

- 修改 `server.bt` 的 `bind` 端口。
- 同步修改 `app.entry`。
- 关闭占用该端口的进程。

## Windows 缺少 WebView2 怎么办
`bt-app` 的桌面窗口依赖 WebView2 Runtime。窗口启动失败并提示 WebView2 相关错误时，安装 Microsoft Edge WebView2 Runtime 后重新运行。

## 远程地址能不能控制本地能力
当前版本 `remote`、`server` 和 `static` 页面都会注入 `window.bt`，并允许调用 `window.bt.call()` 和窗口控制能力。因此远程地址必须是可信地址，不要把 `app.entry` 指向不受控制的第三方页面。

## 开发阶段是否应该开启 devtools
开发阶段可以开启，让 WebView 允许打开开发者工具：

```json
{
  "dev": {
    "watch": true,
    "delay": 500,
    "devtools": true,
    "console": true
  }
}
```

文件变化触发热重载时不会自动弹出开发者工具；需要调试页面时由开发者手动打开。

开启后可以按 `F12` 或 `Ctrl+Shift+I` 打开开发者工具，也可以在页面中调用：

```js
await window.bt.window.open_devtools()
```

发布阶段通常关闭 `dev.devtools`，并按需要把 `dev.console` 设为 `false`。

## 开发时脚本或配置写错会不会退出
开发目录运行时不会因为项目错误直接退出。`app.json` 解析失败、入口文件缺失、`app.main` 缺失、脚本报错或运行时异常时，窗口会显示错误页并继续监听文件变化；修复后会自动重新加载。进入错误页不会强制弹出调试控制台，控制台仍按上一次有效的 `dev.console` 配置处理。

## app.json 和 index.html 同时存在时用哪个
优先使用 `app.json`。只有根目录没有 `app.json` 且存在 `index.html` 时，才会自动生成默认 `app.json` 后运行。`index.html` 中的 `<title>` 不会覆盖窗口标题。

## 打包后为什么资源找不到
检查 `resources` 是否包含需要的文件或目录：

```json
{
  "resources": [
    "index.html",
    "assets/**"
  ]
}
```

`static` 入口、`main.bt`、`server.bt`、`app.json` 和 `app.icon` 会自动补齐。没有 `app.json` 时生成的默认配置还会包含 `assets/**`，用于兼容 Vue/Vite 常见构建产物。页面中引用的其他样式、脚本、图片目录仍必须显式写入 `resources`。如果使用 `exclude`，最终打包集合按 `resources - exclude` 计算。

如果已经设置 `"main": false`，项目不需要 `main.bt`。旧版默认 `app.json` 里可能还在 `resources` 中残留 `"main.bt"`，新版构建会在文件不存在时跳过这个旧资源项；也可以手动从 `resources` 删除它。

## Vue3 或 Vite 项目打开后为什么空白
先确认 `dist/` 下有 `index.html` 和 `assets/`。把 `bt-app.exe` 放入 `dist/` 后首次运行会生成默认 `app.json`，其中包含 `assets/**`。重新执行 `bt-app.exe build` 后，Bundle 会收集这些资源。

`static` 模式会把默认 `index.html` 入口加载为 `bt://app/`，并对无扩展名路由回退到入口 HTML，兼容 Vue Router `createWebHistory()` 的根路径部署方式。缺失的 `.js`、`.css`、图片等带扩展名资源不会回退，会继续返回资源错误，便于定位打包遗漏。

如果 Vue 项目还有 `favicon.ico`、`logo.png`、`static/**` 等不在 `assets/` 下的文件，请在 `app.json` 的 `resources` 中补齐：

```json
{
  "resources": [
    "index.html",
    "assets/**",
    "favicon.ico"
  ]
}
```

## 双开应用为什么登录态会互相影响
WebView 登录态来自 Cookie、localStorage、sessionStorage 等浏览器 profile 数据。默认 `app.storage` 为 `app`，同一个应用名称会使用同一个持久 profile，因此同一个应用双开时登录态会共享，和普通浏览器同一用户配置下打开多个窗口类似。

如果需要两个进程互不影响，例如同一个系统同时登录两个账号，把 `app.storage` 改为 `private`：

```json
{
  "app": {
    "storage": "private"
  }
}
```

`private` 模式每次启动都会创建唯一临时 profile，双开进程不会共享 Cookie/localStorage，因此可同时登录不同账号。若需要恢复旧版所有 bt-app 共用一个全局 profile 的行为，可以设为 `global`。