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

开发阶段可以开启： 发布阶段通常关闭 devtools，并按需要把 console 设为 false。

app.json 和 index.html 同时存在时用哪个

优先使用 app.json。只有根目录没有 app.json 且存在 index.html 时，才会按纯 HTML 项目自动生成配置。

打包后为什么资源找不到

检查 resources 是否包含需要的文件或目录： static 入口、main.bt、server.bt、app.json 和 app.icon 会自动补齐，但页面中引用的其他资源仍建议显式写入，或在纯 HTML 项目中让自动扫描收集本地相对资源。