bt_app 常见问题

bt_app 常见问题

为什么窗口打不开

先在项目目录运行：

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

为什么 entry 加载失败

按模式检查：

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

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

为什么图标没有生效

当前 app.icon 只支持项目内 .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 允许打开开发者工具：

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

发布阶段通常关闭 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 是否包含需要的文件或目录：

static 入口、main.bt、server.bt、app.json 和 app.icon 会自动补齐，但页面中引用的样式、脚本、图片等其他资源必须显式写入 resources。如果使用 exclude，最终打包集合按 resources - exclude 计算。