bt:// 协议
bt:// 协议
功能
bt:// 是 bt_app 内部 WebView 使用的项目资源协议。它把项目目录或打包 Bundle 中的文件映射成页面可访问的 URL。
bt://app/index.html bt://app/assets/app.css bt://app/main.js
该协议不是系统级外部协议，不用于让操作系统或普通浏览器打开 BT 应用。它只在 bt_app 创建的 WebView 内部生效。
使用方式
static 模式下，app.entry 写相对路径即可：
{ "app": { "mode": "static", "entry": "index.html" } }
页面中可以显式引用项目资源：
<link rel="stylesheet" href="bt://app/assets/app.css"> <script src="bt://app/assets/app.js"></script> <img src="bt://app/assets/logo.png">
路径规则
- 主机名必须是
app，例如bt://app/index.html。 - 路径是项目内相对路径。
- 不能访问绝对路径。
- 不能包含
..。 - 开发模式读取项目目录文件，打包模式读取 exe 尾部 Bundle。
内容类型
协议会按扩展名返回常见 Content-Type：
| 扩展名 | 类型 |
|---|---|
.html .htm | text/html; charset=utf-8 |
.css | text/css; charset=utf-8 |
.js | application/javascript; charset=utf-8 |
.json | application/json; charset=utf-8 |
.png .jpg .jpeg .gif .svg .webp .ico | 对应图片类型 |
.wasm | application/wasm |
.txt | text/plain; charset=utf-8 |
调试
需要查看协议请求时，可以设置环境变量：
set BT_APP_TRACE_PROTOCOL=1 ./bt_app.exe run
常见错误
-
资源路径无效：URL 路径为空、包含非法编码或不是安全相对路径。 -
资源不存在或无法读取：文件没有放在项目目录中，或打包时没有进入 Bundle。 -
403：协议主机不是app，或路径试图访问项目外部。