# 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
  }
}
```

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

发布阶段通常关闭 `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` 会自动补齐，但页面中引用的样式、脚本、图片等其他资源必须显式写入 `resources`。如果使用 `exclude`，最终打包集合按 `resources - exclude` 计算。