tinyjs 架构内幕:txiki.js 后端与原生 WebView 如何靠 Unix Socket 协议高效协同
tinyjs 架构内幕:txiki.js 后端与原生 WebView 如何靠 Unix Socket 协议高效协同
tinyjs 是一个让你用纯 JavaScript 构建原生桌面应用的轻量框架:~6 MB 的安装包里只有两个真实文件——一个基于 txiki.js 的后端运行时,和一个用 C++ 写的原生 WebView 启动器。两者之间不跑 HTTP、不开任何端口,而是通过一条位于私有临时目录中的 Unix Socket 管道,用极简的换行分隔协议高效协同。
三层架构:两个进程 + 一个网页
tinyjs 的架构可以概括成"两个进程、一条管道":
┌──────────────────────┐ Unix Socket ┌──────────────────────────┐
│ 后端(txiki.js) │◄────────────►│ 启动器(C++,~1–2 MB) │
│ 你的 main.js │ 行协议 │ · WebView 窗口 │
│ + runtime/bridge.js │ │ · 原生菜单/对话框/托盘 │
└──────────────────────┘ └──────────┬───────────────┘
│ 注入 window.__invoke / eval
┌──────────▼────────────┐
│ 你的页面(file://) │
│ tiny.api.call(...) │
└────────────────────────┘
- 后端进程:由 txiki.js 运行你的
src/backend/main.js,拥有完整的系统能力(文件、网络、进程、SQLite、FFI),并附带桥接库 runtime/bridge.js。 - 启动器进程:平台相关的 C++ 程序(macOS 为 native/launcher-macos.cc、Windows 为 native/launcher-win.cc、Linux 为 native/launcher-linux.cc),负责开 WebView 窗口、渲染你的
index.html,以及一切原生 UI 操作。 - 页面:纯 HTML/CSS/JS,被加载为真正的
file://文档——这样多文件前端和 WebGPU 这类需要安全上下文的 API 才能正常工作。
上图是官方示例 Tiny Deck:左侧 GPU 面板由前端的 WebGPU 直接渲染,而顶部的系统时钟、CPU 负载等数据则来自后端——两者正是通过这条管道协同。
为什么选 Unix Socket,而不是起一个 HTTP 服务?
不少 Electron 之外的方案会让后端起一个本地 HTTP 服务、前端用 fetch('http://127.0.0.1:端口') 通信。tinyjs 刻意避开了这条路,原因写在 runtime/bridge.js 的开头注释里:"No network, no ports"。
- 零端口暴露:没有监听端口,就没有端口冲突,也没有被局域网扫描或本机其他进程误连的可能。
- 私有目录隔离:Socket 文件建在一个权限
0700的全新临时目录里(runtime/bridge.js),其他用户根本无法访问,安全边界由文件系统直接保证。 - 协议极简:换行分隔的文本行 + JSON 载荷,无需 HTTP 头部、状态码、Content-Length 那一整套,调试时直接就能看到人话。
- 生命周期天然绑定:关窗即结束。窗口一关,启动器进程退出,后端检测到管道断开后自动清理退出——没有残留的僵尸服务。
在 runtime/bridge.js 中,后端用 tjs.listen('pipe', sockPath) 开始监听,随后把 Socket 路径作为命令行参数传给启动器(runtime/bridge.js)。启动器侧则是标准的 POSIX 流程:socket(AF_UNIX, SOCK_STREAM) → connect(),见 native/launcher-linux.cc。
一次 api.call() 的完整旅程
前端与后端的 RPC 协议只有几种行格式(完整定义见 runtime/bridge.js 的注释):
| 方向 | 行格式 | 含义 |
|---|---|---|
| 启动器 → 后端 | CALL <id> <json-参数> |
页面调用了 tiny.api.call(...) |
| 后端 → 启动器 | RET <id> 0 <json> |
应答:resolve(状态 0)或 reject |
| 后端 → 启动器 | EVAL <js> |
在页面里执行 JS(后端推送事件) |
| 后端 → 启动器 | TITLE / SIZE / DLG / QUIT |
窗口标题、尺寸、原生对话框、退出 |
具体链路是这样的:
- 页面调用
await tiny.api.call('hello', { name: 'world' })。前端 shim 其实薄得惊人——核心就是 runtime/tiny.js 中的一行:window.__invoke(JSON.stringify({ method, params }))。 - 启动器收到消息后,拼成
CALL 42 ["hello",{"name":"world"}]一行,写入 Socket。 - 后端 bridge 解析参数,调用你
export const api里定义的hello函数。 - 后端回
RET 42 0 {"result":"hi world"},启动器用这个值 resolve 掉页面里那个 Promise。
启动器侧的读取循环非常朴素:一个专用线程不断 read() Socket,按 \n 切分完整行后派发到 UI 线程执行,见 native/launcher-linux.cc。而 tiny.js 整个客户端在构建时会被 native/gen-client.sh 内联为 C 字符串常量 TINY_CLIENT_JS,直接编译进每个启动器——所以页面上永远有 tiny 全局对象,无需任何 <script> 标签。
后端推送:让页面"活"起来
管道是双向的,后端不仅能应答,还能主动"推"。比如你在后端写:
export function init(app) {
setInterval(() => app.push('tick', Date.now()), 1000);
}
页面侧用 tiny.api.on('tick', (t) => ...) 接收。push 经 EVAL 行抵达页面后调用 window.__emit 分发事件。像实时可视化、定时状态刷新、通知提醒这类场景全靠它。
上图的 amp 示例就是一个典型:频谱数据来自后端的音频采样,每秒多次推送到页面,前端画布实时绘制——全部走这条私有管道,页面端只关心数据本身。
多窗口:同一条管道,按窗口寻址
tinyjs 支持一个后端服务多个 WebView 窗口。协议用 @<窗口id> 后缀做寻址:CMD@side 指定操作某个子窗口,裸的 CMD 则指主窗口(native/launcher-linux.cc 中的 peel_target 就是干这件事的)。后端可通过 app.openWindow() 开窗、app.window('id') 单独控制某窗口,页面侧的 tiny.win.* 则自动只作用于自己所在的窗口。
上图 Nib 编辑器里悬浮的"New Document"小窗,就是由主窗口通过 tiny.win.open() 打开的第二窗口——两个 WebView、一套后端、一条管道。
跨平台:同一套协议,三种传输
三端运行完全相同的 runtime 和协议,差异只在启动器实现和传输层(见 README.md 的 Portability 章节):
| 平台 | 启动器 | WebView | 传输层 |
|---|---|---|---|
| macOS | launcher-macos.cc |
WebKit | Unix Socket |
| Linux | launcher-linux.cc |
GTK3 + WebKitGTK 4.1 | Unix Socket |
| Windows | launcher-win.cc |
WebView2 | 命名管道 \\.\pipe\… |
Windows 没有 Unix Socket,改用命名管道;由于 Windows 管道的默认权限允许任何用户只读连接,tinyjs 额外加了一道握手:启动器连接后必须先发送一行 HELLO <随机令牌>(令牌只存在于后端传给启动器的环境变量里),验证通过才放行——只读的连接永远发不出令牌,见 runtime/bridge.js。libuv 的 pipe 抽象统一了两种传输,后端代码一行都不用改。
安全设计:这条管道为什么可信
- 0700 私有目录:Socket 文件对其他用户不可见,从文件系统层面挡住了本机攻击者。
- 无网络面:不监听任何 TCP/UDP 端口,攻击面只有本机同用户进程。
- 来源戳记:启动器在每条
CALL末尾附上 WebKit 报告的真实来源(origin),后端的 API 能力门(tinyjs.json的"api"字段)据此判断调用是否被允许——页面自报的身份不算数。 - 失败即关闭:安全配置写错(如拼错的预设名)会拒绝一切访问并打印警告,而不是静默放行。
想深入源码?从这里开始
- README.md —— "How it works" 一节的完整架构图与协议表
- runtime/bridge.js —— 后端桥接库:Socket 建立、协议编解码、能力探测
- runtime/tiny.js —— 注入页面的前端客户端 shim
- native/launcher-linux.cc —— Linux 启动器(含 Socket 读取线程与消息分发)
- native/launcher-macos.cc / native/launcher-win.cc —— 另两端的启动器
- native/gen-client.sh —— 把 tiny.js 编译进启动器的构建脚本
整套架构的智慧在于"克制":不引入微框架、不引入本地服务器、不把前端当服务端,只用操作系统早就提供的 Unix Socket 加几十行协议,就把一个完整桌面应用拆成了"有系统权限的后端"与"只画界面的前端"两个各司其职的进程。



