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.storage`	string	否	`app`	WebView 存储策略。`app` 表示按应用名称使用独立持久 profile；`private` 表示每次启动使用唯一临时 profile，双开互不共享 Cookie/localStorage；`global` 表示使用旧版全局共享 profile。
`app.file_associations`	object[]	否	`[]`	Windows 文件关联列表。只由打包后的 Bundle 应用在当前用户下注册，开发目录运行不会注册通用 `bt_app.exe`。
`app.main`	string/boolean/null	否	自动尝试 `main.bt`	前端 `bt.call()` 可调用的 BT 主脚本。字符串表示指定脚本；`false` 或空字符串表示不执行；`true`、`null` 或省略表示自动查找 `main.bt`。

app.file_associations 字段

每个关联对象可同时声明多个扩展名。打包应用启动后会把自身注册为这些扩展名的打开程序，并添加资源管理器右键菜单；文件路径会作为启动参数传入，可通过 window.bt.app.args() 读取。

字段	类型	必填	默认值	有效范围或可选值	含义
`extensions`	string[]	是	无	每项为 1 到 32 个 ASCII 字母或数字；可带前导 `.`，读取后会移除并转成小写；全配置内不能重复	需要关联的文件扩展名。
`icon`	string	否	`app.icon`	项目内相对路径，只支持 `.ico` 文件	文件类型专属图标。构建时嵌入 exe 的独立图标资源组，资源管理器中的关联文件使用该图标；右键菜单仍显示应用主图标。
`description`	string	否	`<app.title> 文档`	非空文本，不允许 NUL	Windows 中显示的文件类型说明。
`context_menu`	string	否	`以 <app.title> 打开`	非空文本，不允许 NUL	文件资源管理器右键菜单文本。

file_associations[].icon 和 app.icon 作用不同：前者表示文件类型图标，后者表示 exe、窗口和任务栏中的应用图标。关联图标会直接嵌入单文件 exe，不需要额外写入 resources；省略时继续复用应用主图标，兼容旧配置。

Windows 关联写入 HKEY_CURRENT_USER\\Software\\Classes，不需要管理员权限，也不会修改其他用户。系统会尊重用户已经在 Windows 设置中明确选择的默认应用；这种情况下右键菜单和“打开方式”仍会出现，用户可在系统设置中把新应用设为默认。bt_app 不删除带签名保护的 UserChoice，也不会在每次启动时抢回用户后来选择的其他默认程序。

window 字段

字段	类型	必填	默认值	说明
`window.width`	number	否	`800`	主窗口初始宽度，单位为逻辑像素。写 `0` 会回退到默认值。
`window.height`	number	否	`500`	主窗口初始高度，单位为逻辑像素。写 `0` 会回退到默认值。
`window.resizable`	boolean	否	`true`	是否允许用户调整窗口大小。
`window.fullscreen`	boolean	否	`false`	是否全屏启动。
`window.hide_titlebar`	boolean	否	`false`	是否隐藏系统标题栏。隐藏后需要页面自己提供拖动、关闭等交互；Windows 使用系统 DWM 投影并抑制默认实线边框。Windows 10 保留左、右、下系统细边框，并在页面根节点注入 `data-bt-windows-10-frame="true"`，供自绘标题栏按需补齐顶部边线。Windows 11 自绘主题应调用 `window.bt.window.set_background_color()` 同步原生底色，避免顶部 1px 非客户区透出系统默认色。
`window.always_on_top`	boolean	否	`false`	是否置顶窗口，适合悬浮工具、监控面板等场景。

dev 字段

字段	类型	必填	默认值	说明
`dev.watch`	boolean	否	`true`	开发目录运行时是否监听资源变化并自动刷新页面。打包后的 Bundle 运行不生效。
`dev.delay`	number	否	`500`	文件变化后的防抖时间，单位为毫秒。连续保存多个文件只刷新一次。
`dev.devtools`	boolean	否	`false`	是否允许打开 WebView 开发者工具。开启后可按 `F12` 或 `Ctrl+Shift+I` 打开，也可调用 `window.bt.window.open_devtools()`。建议只在开发阶段开启；文件变化热重载不会自动弹出开发者工具。
`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 字符串时自动加入该脚本。
app.main 为 false 或空字符串时不需要主脚本；旧配置中 resources 残留的 main.bt 若文件不存在会被跳过。
当前目录存在 server.bt 时自动加入 server.bt。
配置了 app.icon 时自动加入图标文件。

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

默认生成的 app.json

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

默认配置中的 app.main 指向 main.bt。如果目录中还没有 main.bt，运行器会创建一个空文件，确保项目可以直接启动。默认资源会包含 assets/**，适配 Vue/Vite 常见构建产物。需要打包其他目录或文件时，请手动把它们写入 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 格式的图标文件。
app.file_associations[].icon 同样只接受项目内 .ico 文件；文件不存在时构建会失败。
app.file_associations 只在 Windows 打包应用启动时注册；仅执行 bt_app.exe build 不会修改开发机的文件关联。
index.html 只作为页面入口，不承担配置职责。