# bt:// 协议

## 功能
`bt://` 是 `bt-app` 内部 WebView 使用的项目资源协议。它把项目目录或打包 Bundle 中的文件映射成页面可访问的 URL。

```text
bt://app/
bt://app/index.html
bt://app/assets/app.css
bt://app/main.js
```

该协议不是系统级外部协议，不用于让操作系统或普通浏览器打开 BT 应用。它只在 `bt-app` 创建的 WebView 内部生效。

## 使用方式
`static` 模式下，`app.entry` 写相对路径即可：

```json
{
  "app": {
    "mode": "static",
    "entry": "index.html"
  }
}
```

页面中可以显式引用项目资源：

```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">
```

## 路径规则
- `bt://app/` 会映射到当前 `static` 入口文件，默认是 `index.html`。
- 主机名必须是 `app`，例如 `bt://app/index.html`。
- 路径是项目内相对路径。
- 不能访问绝对路径。
- 不能包含 `..`。
- 开发模式读取项目目录文件，打包模式读取 exe 尾部 Bundle。
- `static` 模式下，无扩展名路径在资源不存在时会回退到入口 HTML，用于兼容 SPA history 路由；带扩展名的资源不存在时仍返回资源错误。

## 内容类型
协议会按扩展名返回常见 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` |

## 调试
需要查看协议请求时，可以设置环境变量：

```bash
set BT_APP_TRACE_PROTOCOL=1
./bt-app.exe run
```

## 常见错误
- `资源路径无效`：URL 路径包含非法编码或不是安全相对路径。
- `资源不存在或无法读取`：文件没有放在项目目录中，或打包时没有进入 Bundle。
- `403`：协议主机不是 `app`，或路径试图访问项目外部。