app.json 配置

功能

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

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

完整示例

app 字段

字段	类型	必填	默认值	有效范围或可选值	说明
`app.id`	string	否	根据 `app.name` 生成 `org.btlang.<name>`	小写反向域名形式；至少两段；每段只能包含 ASCII 字母、数字、`_`、`-`，且首尾为字母或数字	跨版本保持稳定的应用标识。显式配置后用于 WebView profile、凭据和应用数据隔离，不应因显示名称或输出文件名变化而修改。
`app.name`	string	否	`BTApp`	单个文件名片段；不能包含路径或 Windows 文件名非法字符	应用内部名称，也是默认打包输出文件名。
`app.title`	string	否	`BT 桌面应用`	非空文本	窗口标题。用户看到的应用名称通常写在这里。
`app.version`	string	否	`1.0.0`	非空文本	应用版本，并写入 BTR 软件信息。
`app.description`	string	否	无	非空文本或省略	应用说明。Windows 打包时写入 exe 的 `FileDescription` 元信息。
`app.copyright`	string	否	无	非空文本或省略	版权说明。Windows 打包时写入 exe 的 `LegalCopyright` 元信息。
`app.mode`	string	否	`static`	`static`、`server`、`remote`	运行模式。
`app.entry`	string	否	按模式决定	`static` 为项目内安全相对路径；`server`、`remote` 为 HTTP/HTTPS URL	窗口入口。`static` 默认 `index.html`，`server` 默认 `http://127.0.0.1:18280`，`remote` 默认 `https://example.com`。
`app.icon`	string	否	内置图标	项目内安全相对 `.ico` 路径	用于运行窗口图标、BTR 工具条展示和 Windows 打包 exe 图标。
`app.storage`	string	否	`app`	`app`、`private`、`global`	WebView 存储策略。`app` 按应用标识使用独立持久 profile；`private` 每次启动使用唯一临时 profile；`global` 使用旧版全局共享 profile。
`app.file_associations`	object[]	否	`[]`	见下表	Windows 业务文件关联列表。只由打包后的 exe 应用注册；外部 BTR 不注册其中声明的关联。
`app.main`	string/boolean/null	否	自动尝试 `main.bt`	安全相对 `.bt` 路径、`false`、空字符串、`true` 或 `null`	前端 `bt.call()` 可调用的 BT 主脚本。字符串表示指定脚本；`false` 或空字符串表示不执行；其他默认形式自动查找 `main.bt`。

建议从项目创建时就显式写入 app.id。未写时仍按旧行为兼容：运行时根据当前 app.name 生成默认 ID，并继续沿用旧版按名称保存的数据位置；一旦显式设置稳定 ID，后续修改 app.name 或 app.title 不会更换应用 profile 与数据目录。

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 无标题栏窗口会关闭产生 1px 白边的系统阴影。
`window.transparent`	boolean	否	`false`	是否在创建时同时启用原生窗口和 WebView 透明背景。设为 `true` 时必须同时设置 `hide_titlebar: true`；修改后必须重启应用，热重载不会切换透明状态。
`window.always_on_top`	boolean	否	`false`	是否置顶窗口，适合悬浮工具、监控面板等场景。

主窗口启动时会先以无边框、无投影且隐藏的状态创建 WebView。非透明页面开始加载后会显示 bt_app 内置的无边框加载动画；首个页面完成加载后，bt_app 才应用 hide_titlebar 对应的最终边框和系统投影。透明窗口不会绘制矩形加载背景，而是保持隐藏到页面首帧完成。该时序由运行时统一处理，可避免 Windows 非客户区边线和 WebView 默认白底在页面首帧前闪现，项目页面不需要额外制作启动遮罩。

透明窗口

透明窗口适合悬浮工具、圆角面板、桌面挂件以及带 Alpha 通道的 PNG 界面。它不是运行期 API，而是窗口创建期配置：

页面根节点必须保持透明，只让实际界面容器绘制背景和圆角：

transparent: true 会关闭矩形原生阴影，阴影需要由 HTML/CSS 绘制并在窗口尺寸内预留透明边距。PNG 和 HTML 元素可以使用半透明像素；完全透明的圆角区域仍属于原生矩形窗口的命中范围，不会自动点击穿透到下层应用。

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，以便修改配置后自动恢复。window.transparent 同时影响原生窗口和 WebView，只能在窗口创建时应用；改变该字段后需要重启 bt_app。

开发目录运行时遇到 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 计算，该规则同时用于打包和开发模式文件监听。dist/ 构建输出目录始终不会进入资源产物。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 不会修改开发机的文件关联。
window.transparent=true 必须配合 window.hide_titlebar=true，并由页面把 html、body 背景设为 transparent。
index.html 只作为页面入口，不承担配置职责。