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 允许打开开发者工具：

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

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

发布阶段通常关闭 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 会自动补齐。没有 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 中补齐：

双开应用为什么登录态会互相影响

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

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

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