app.json 配置

功能

app.json 是 bt_app 的桌面应用配置文件。它描述应用名称、窗口、入口、运行模式、图标、主脚本和打包资源。

app.json 是唯一配置来源。项目根目录不存在 app.json 但存在 index.html 时，bt_app 会自动写入默认 app.json 后再启动；index.html 中的 <title> 和自定义标签不会覆盖应用配置。

完整示例

app 字段

字段	类型	必填	默认值	说明
`app.name`	string	否	`BTApp`	应用内部名称，也是默认打包输出文件名。只能是单个文件名片段，不能包含路径或 Windows 文件名非法字符。
`app.title`	string	否	`BT 桌面应用`	窗口标题。用户看到的应用名称通常写在这里。
`app.version`	string	否	`1.0.0`	应用版本。当前主要用于配置记录。
`app.description`	string	否	无	应用说明。Windows 打包时写入 exe 的 `FileDescription` 元信息。
`app.copyright`	string	否	无	版权说明。Windows 打包时写入 exe 的 `LegalCopyright` 元信息。
`app.mode`	string	否	`static`	运行模式，只能是 `static`、`server`、`remote`。
`app.entry`	string	否	按模式决定	窗口入口。`static` 默认 `index.html`，`server` 默认 `http://127.0.0.1:18280`，`remote` 默认 `https://example.com`。
`app.icon`	string	否	内置图标	项目内相对路径，当前只支持 `.ico` 文件。用于运行窗口图标和 Windows 打包 exe 图标。
`app.main`	string/boolean/null	否	自动尝试 `main.bt`	前端 `bt.call()` 可调用的 BT 主脚本。字符串表示指定脚本；`false` 或空字符串表示不执行；`true`、`null` 或省略表示自动查找 `main.bt`。

window 字段

字段	类型	必填	默认值	说明
`window.width`	number	否	`800`	主窗口初始宽度，单位为逻辑像素。写 `0` 会回退到默认值。
`window.height`	number	否	`500`	主窗口初始高度，单位为逻辑像素。写 `0` 会回退到默认值。
`window.resizable`	boolean	否	`true`	是否允许用户调整窗口大小。
`window.fullscreen`	boolean	否	`false`	是否全屏启动。
`window.hide_titlebar`	boolean	否	`false`	是否隐藏系统标题栏。隐藏后需要页面自己提供拖动、关闭等交互。
`window.always_on_top`	boolean	否	`false`	是否置顶窗口，适合悬浮工具、监控面板等场景。

dev 字段

字段	类型	必填	默认值	说明
`dev.watch`	boolean	否	`true`	开发目录运行时是否监听资源变化并自动刷新页面。打包后的 Bundle 运行不生效。
`dev.delay`	number	否	`500`	文件变化后的防抖时间，单位为毫秒。连续保存多个文件只刷新一次。
`dev.devtools`	boolean	否	`false`	是否允许打开 WebView 开发者工具。建议只在开发阶段开启；文件变化热重载不会自动弹出开发者工具。
`dev.console`	boolean	否	`true`	是否启用调试控制台。打包时为 `false` 会把 Windows exe 改为 GUI 子系统，双击时不弹控制台。

开发模式支持 F5、Ctrl+R 和 Cmd+R 刷新当前页面。dev.watch=true 时，resources - exclude 命中的文件保存、新增、删除或重命名后会自动刷新页面。dev.watch=false 时不会监听普通资源变化，但仍会监听 app.json，以便修改配置后自动恢复。

开发目录运行时遇到 app.json 解析失败、入口文件缺失、app.main 缺失或脚本执行异常时，会在窗口内显示统一错误页并继续监听文件变化；修复后会自动重新加载。热重载错误状态会沿用上一次有效配置中的控制台设置，不会因为进入错误页而强制弹出控制台。

resources 字段

字段	类型	必填	默认值	说明
`resources`	string[]	否	`[]`	打包时进入 Bundle 的资源规则，支持普通相对文件、glob 和 `assets/**` 这类递归目录规则。
`exclude`	string[]	否	`[]`	排除打包与开发监听的资源规则，优先级高于 `resources`。

构建时还会自动补齐必要资源：

当前目录存在 app.json 时自动加入 app.json。
static 模式自动加入 app.entry 指向的入口文件。
app.main 自动模式下如果存在 main.bt，自动加入 main.bt。
指定 app.main 字符串时自动加入该脚本。
当前目录存在 server.bt 时自动加入 server.bt。
配置了 app.icon 时自动加入图标文件。

最终资源集合按 resources - exclude 计算，该规则同时用于打包和开发模式文件监听。resources 和 exclude 只能写项目内相对路径，不能写绝对路径，不能包含 ..。普通文件不存在会打包失败；普通目录会递归收集目录内文件；assets/** 会递归收集目录内文件。

默认生成的 app.json

项目根目录没有 app.json，但存在 index.html 时，会生成以下默认配置：

默认配置中的 app.main 指向 main.bt。如果目录中还没有 main.bt，运行器会创建一个空文件，确保项目可以直接启动。需要打包 style.css、main.js、图片等额外资源时，请手动把它们写入 resources，bt_app 不再从 HTML 标签中自动扫描资源。

mode运行模式

static

该模式为静态HTML加载方式，需要配置app.entry为入口 HTML 文件路径，例如 index.html。

server

该模式会执行当前目录的 server.bt 脚本，并启动Web服务，需要配置 app.entry 为该Web服务的完整URL，例如 http://127.0.0.1:18280。

提示：请确保 server.bt 脚本文件存在，并能正确启动 BT Web 服务。

remote

该模式会直接打开远程URL，需要配置 app.entry 为远程URL，例如 https://example.com。

运行机制

以上三种运行模式都会自动执行当前目录的 app.main 脚本，并注入 window.bt 对象，用于与BT脚本进行交互。

如果 app.main 配置为 false，则不会执行该脚本。
如果 app.main 配置不存在，则自动查找当前目录的 main.bt 脚本并执行。

注意事项

app.name 和 app.title 不同：name 为打包输出的文件名，title 为程序窗口的标题。
app.icon 只接受 .ico 格式的图标文件。
index.html 只作为页面入口，不承担配置职责。