打包构建

介绍

bt_app 支持两种桌面应用产物：

build 生成包含 bt_app 运行时和应用资源的独立 exe。
pack 生成只包含应用配置与资源的 .btr 软件文件，由已安装的 bt_app 运行时打开。

.btr 对用户表示可直接运行的 BT 软件，不是需要手工解压或安装依赖的开发包。内部使用带版本描述的压缩资源容器，根目录包含 app.json 和运行时生成的 btr.json，不包含 bt_app 自身。因此多个小工具可以共用一个 bt_app 运行时文件，不必为每个工具复制完整 exe。

构建独立 exe

在项目目录运行：

如果当前目录没有 app.json 但存在 index.html，构建前会先生成默认 app.json。默认配置会包含 app.json、index.html 和常见前端构建目录 assets/**。页面引用的其他根目录资源、图片目录或自定义静态目录仍需要手动写入 resources。

输出位置：

构建时会先生成 BTR 资源容器，再在 dist 中生成临时 exe，完成图标、元信息、BTR 注入和读回校验后才替换最终输出。这样中途失败不会留下一个没有应用资源的半成品 exe。若 dist/{app.name}.exe 正在运行或被其他程序占用，构建会明确失败并提示先关闭目标程序后重试。

桌面构建只生成单个应用 exe，不会额外写出 FFI 许可证旁路文件。

构建 BTR 软件

在项目目录运行：

输出位置：

pack 和 build 使用完全相同的 app.json、资源收集规则及回读校验；区别仅是 pack 不附带 bt_app 运行时。BTR 会记录容器格式版本、构建时 BT 版本和最低运行时版本。运行时在加载页面或执行 app.main 前完成格式、版本、路径、条目数量、单文件大小和展开总大小校验。

运行和检查 BTR：

info 只读取元数据，不执行 app.main、server.bt 或页面脚本。直接把 .btr 路径作为第一个参数是 run 的简写。需要向软件传递业务参数时使用 -- 分隔：

页面可通过 window.bt.app.args() 读取 document.md，不会看到 bt_app 命令名、BTR 路径或 --。

Windows 下，先把最终安装位置的 bt_app 加入 PATH，再执行一次：

之后 .btr 可通过双击交给该 bt_app 打开。仅加入 PATH 不会自动建立 Windows 文件关联；如果用户此前选择过其他默认程序，Windows 仍可能要求在“打开方式”中确认。关联只写当前用户注册表，不需要管理员权限，也不会覆盖系统保护的 UserChoice。

资源收集

resources 支持普通文件、目录和 glob：

构建阶段会自动加入必要资源，包括 app.json、static 入口、主脚本、server.bt 和图标。最终打包集合按 resources - exclude 计算，普通目录和 assets/** 都会递归收集目录下所有文件。dist/ 始终排除，避免宽泛资源规则把上一轮 exe 或 BTR 递归打入新产物。

图标和元信息

配置 app.icon 后，构建会校验图标文件存在，并在 Windows 上写入输出 exe 的图标资源：

当前 app.icon 只支持 .ico。description 和 copyright 会写入 Windows exe 版本资源。

文件关联可以声明独立的文档图标。构建器会把每个 file_associations[].icon 嵌入 exe 的独立 PE 图标资源组；关联文件使用文档图标，资源管理器右键菜单仍使用应用主图标：

关联图标仅支持项目内相对 .ico 路径，不需要额外加入 resources。省略 file_associations[].icon 时，文件类型继续复用 app.icon；没有配置应用图标时则使用 bt_app 内置图标。

控制台

dev.console 为 false 时，构建会把 Windows exe 子系统改成 GUI，双击运行时不弹出控制台。

开发阶段建议使用 dev.console:true，便于查看启动摘要、错误和 echo() 输出。

其他命令

run：不传目标时运行当前目录项目；传目录时运行指定开发项目；传 .btr 时运行指定 BTR 软件。
info：安全读取 BTR 软件信息，不执行软件代码。
associate：Windows 当前用户下把通用 bt_app 注册为 .btr 打开程序。
bundle-check：检查当前 exe 是否包含应用资源，并打印资源文件列表；同时兼容旧版 Bundle。

平台说明

当前 build 逻辑输出单个 .exe 文件，Windows 下会处理 GUI 子系统、exe 图标和元信息；pack 输出跨产物共用的 .btr 资源软件。桌面运行时本身仍需为目标操作系统和架构单独构建。