一个 Electron 写的小工具,安装包 120MB,装完占 300MB。产品经理问:同样就一个文本框加一个列表,为什么这么大?团队试了 Tauri,打出来几 MB,皆大欢喜。demo 在开发机上跑得很顺。到了客户现场,Windows 10 的老镜像上双击没反应——WebView2 运行时没装。换一台 Linux,页面布局全乱,那台机器的 WebKitGTK 比开发机低两个大版本。再回到代码,负责人发现主进程里几千行 Node 逻辑,迁到 Tauri 之后一行都用不上。
这不是 Tauri 的缺陷,是设计决定的:它不替你带浏览器,也不替你带 Node。省下的体积,换成了对系统组件的依赖;省下的运行时,换成了一次结构性重写。
这篇讲清 Tauri 2 的结构、权限模型、三个平台 WebView 的差异,以及从 Electron 迁移时哪些能搬、哪些必须重写。版本说明:本机有 rustc 1.99.0 和 Tauri CLI 2.12.4,最小应用构建出 8,746 KB 的 exe、启动 67–68 ms;字段名在 2.x 小版本间调整过,以项目版本为准;NSIS 打包卡在 os error 5,安装包未验证。
现场:体积小了,依赖换了地方
先把数字摆清楚。Electron 把 Chromium 和 Node 一起打进安装包,80 到 150MB 是常态;Tauri 复用系统 WebView,只带自己的 Rust 可执行文件和前端资源,几 MB 到十几 MB 是常态。
但「几 MB」有个前提:WebView2 运行时是系统组件,不计入安装包。目标机器没有它时,安装器要么联网下载引导程序,要么塞一个固定版本离线包,后者会让安装包增加上百 MB,体积优势立刻缩水。
第二个变化更隐蔽:进程模型。Electron 主进程是 Node,渲染进程是 Chromium,preload 是桥。Tauri 主进程是 Rust,渲染层是系统 WebView,桥是 invoke 加 command。原来写在 main.js 里的 fs、http、child_process,都要在 Rust 里重做;依赖 npm 包的逻辑,要么找 Rust 替代,要么打 sidecar 把 Node 带回来。
架构:Rust 外壳 + 系统 WebView
Tauri 的运行时可以分成五层,和 Electron 一一对应,但每一层的归属不同。
file:// 的路径问题。invoke,Rust 侧执行 #[tauri::command],参数和返回值都经 serde 序列化。和 Electron 最大的结构差别是:Electron 的渲染进程和主进程都是你的运行时,版本由你锁定;Tauri 的渲染层是操作系统的组件,版本由用户决定。这带来体积优势,也带来兼容性债务。你不再需要升级 Chromium,但也不能假设用户有最新的 Chromium。
IPC 也和 Electron 不同。Electron 的 ipcRenderer 传什么由你自己定,Tauri 的 command 参数必须能被 serde 反序列化,返回值必须能序列化成 JSON。传一个大文件不能直接塞进参数,要分块或流式;传复杂对象要先定义结构体。约束比 JavaScript 世界严格,但错误也更早暴露。
场景走查:读一个本地 Markdown
需求:窗口里点一个按钮,读应用数据目录 notes 子目录下的 welcome.md,显示在页面上。先确认工具链,再建项目。
rustup --version
cargo --version
npm create tauri-app@latest
脚手架会问项目名、前端模板和包管理器,按提示选一个最简模板即可。进入目录后执行 npm install,再执行 npm run tauri dev。第一次要编译 Rust 依赖,几分钟到十几分钟不等。
平台依赖要先装:Windows 需要 Microsoft C++ Build Tools 和 WebView2 运行时;macOS 需要 Xcode Command Line Tools;Linux 需要 WebKitGTK 开发包(Tauri 2 对应 webkit2gtk-4.1)以及构建工具。各发行版的包名不一样,安装命令以官方文档为准,待确认。
Rust 侧的命令写在 src-tauri/src/lib.rs:
use std::fs;
use tauri::Manager;
#[tauri::command]
fn read_note(app: tauri::AppHandle, name: String) -> Result<String, String> {
if !name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-') {
return Err("名称不合法".into());
}
let dir = app
.path()
.app_data_dir()
.map_err(|e| e.to_string())?
.join("notes");
fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
let file = dir.join(format!("{name}.md"));
fs::read_to_string(file).map_err(|e| e.to_string())
}
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
tauri::Builder::default()
.invoke_handler(tauri::generate_handler![read_note])
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
几个关键点:#[tauri::command] 把普通函数变成前端可调用的命令;参数和返回值都要能序列化,返回 Result<T, E> 时,Err 会变成前端的 reject;generate_handler! 是命令注册表,没写进去的命令,前端 invoke 会报 not found;app.path().app_data_dir() 需要引入 Manager trait,路径在不同平台分别是用户数据目录下的应用文件夹。
配置里把窗口和前端资源对上:
{
"productName": "note-reader",
"identifier": "cn.example.note-reader",
"build": {
"frontendDist": "../dist"
},
"app": {
"withGlobalTauri": true,
"windows": [{ "title": "笔记", "width": 800, "height": 600 }],
"security": {
"csp": "default-src 'self'; img-src 'self' data:"
}
}
}
权限文件 src-tauri/capabilities/default.json 里只开需要的几项:
{
"identifier": "default",
"description": "主窗口的最小权限",
"windows": ["main"],
"permissions": [
"core:default"
]
}
前端调用只有几行:
const invoke = window.__TAURI__.core.invoke;
document.querySelector('#read').addEventListener('click', async () => {
try {
const text = await invoke('read_note', { name: 'welcome' });
document.querySelector('#out').textContent = text;
} catch (error) {
document.querySelector('#out').textContent = '读取失败:' + error;
}
});
预期:窗口打开,点按钮显示 welcome.md 的内容;文件不存在时显示读取失败。把调用的 name 改成 ../secret,应该在 Rust 侧被拒绝,而不是读到上级目录。把参数改成数字,应该看到反序列化失败,而不是悄悄转成字符串。
这段走查要理解三件事:命令注册、参数类型、目录权限。三者任一没配对,报错都发生在运行时,前端只会收到一个笼统的错误字符串。调试时先看 Rust 侧的控制台,再看前端 catch 到的 error。
withGlobalTauri 的位置,在不同 2.x 版本间可能微调。拿不准时以项目实际版本的 schema 和生成的权限文件为准,待确认。用 @tauri-apps/api 的 invoke 时,导入路径是 @tauri-apps/api/core,不用依赖全局对象。权限模型:capabilities 默认拒绝
Tauri 1 用 allowlist 在配置里勾选能力,Tauri 2 换成 capabilities 加 permissions:每个窗口挂一个 capability 文件,文件里列出允许的权限。默认对插件和核心能力什么都不允许,要用什么就加什么。这个方向和 Electron 的「默认全开、靠配置关掉」相反。
fs 这类插件权限还需要 scope,指定能碰哪些目录。只写 allow-read-text-file 不给 scope,读取照样被拒;scope 里可以用 $APPDATA 这类路径变量,具体变量名和展开规则以版本文档为准,待确认。scope 要写到具体子目录,不要用通配整个用户目录。一条只读、限定目录的权限项大致长这样:
{
"identifier": "fs:allow-read-text-file",
"allow": [{ "path": "$APPDATA/notes/**" }]
}
注意,上面的 read_note 是自定义 command,内部用 std::fs 直接读,不经过 fs 插件,所以 capability 里的 fs 权限对它不起作用,路径校验只能靠函数里的白名单和固定目录。只有当前端直接调用 fs 插件命令时,这条权限和 scope 才会生效。
不要图省事写 fs:default 或 shell:allow-execute。前者往往包含写和删除,后者等于给前端一个命令执行器。前端一旦被 XSS,能调用的就是 capability 里列出的全部能力,权限清单就是攻击面清单。
权限模型只约束「能调用哪个命令」,不约束「命令内部做什么」。如果 command 自己接收任意路径、自己拼 shell 字符串,权限配置再严也没用。校验必须写在 Rust 函数里,和 Electron 那篇讲的主进程校验是同一件事。
插件:dialog、fs、shell
常用插件有三个:dialog 负责打开和保存对话框,只返回路径,不读内容;fs 负责读写,受 scope 约束;shell 负责用系统程序打开 URL 或文件,也能执行命令。它们各自有 Rust crate 和前端 npm 包,两边都要装。
Rust 侧写 .plugin(tauri_plugin_dialog::init()),前端装 @tauri-apps/plugin-dialog,两边的版本要匹配。权限在 capability 里声明,比如 dialog:default、fs:allow-read-text-file。插件不是装了就能用,没声明权限,调用会被拒绝。
shell 要分两种用法:open 是「用默认程序打开一个 URL 或文件」,execute 是「运行一个程序」。前者风险可控,后者等于把执行能力交给前端。确实需要跑外部程序时,优先用 sidecar:把二进制打进安装包,命令和参数在 Rust 侧固定,前端只能传受限的输入。sidecar 会让体积变大,但比开放 execute 安全。
三个平台的 WebView 差异
同一份前端代码,在三个平台上不是同一套实现。这是 Tauri 最需要提前评估的地方。
| 平台 | WebView | 版本由谁决定 | 典型问题 | 打包注意 |
|---|---|---|---|---|
| Windows | WebView2(Chromium) | 系统 Evergreen,随 Edge 更新 | 老镜像、LTSC、Server 没有运行时;企业可能锁版本 | 安装器可选在线引导、离线包或跳过 |
| macOS | WKWebView | 系统 Safari 与 OS 版本 | 旧系统不支持新 CSS/JS,需覆盖最低系统测试 | 签名与公证,否则 Gatekeeper 拦截 |
| Linux | WebKitGTK | 发行版包管理器 | 版本碎片、字体渲染差异、依赖缺失 | 按目标发行版打不同包,容器里测 |
差异不止 CSS。JS 的新 API、字体渲染、滚动条、输入法、视频编码、打印,都可能不同。开发机上用的是最新 Chromium,客户机上可能是两年前的 WebKit。
做法是定一个最低支持版本,在那台机器上跑主流程;把 :has()、容器查询、backdrop-filter 这类特性查一遍兼容表;关键布局用 flex/grid 基础能力,别把体验押在新语法上。前端构建的目标浏览器也要相应调低,别只按 Chromium 最新版转译。
体积与内存:优势到底来自哪
Electron
自带 Chromium 和 Node,安装包 80 到 150MB;运行时版本统一,行为可预测,代价是每个应用都带一套浏览器。
Tauri
复用系统 WebView 和 Rust 二进制,安装包几 MB 到十几 MB;运行时版本分散,行为依赖用户机器。
体积优势来自三件事:不打包浏览器内核、不带 Node 运行时、前端资源压缩后本身很小。Rust 二进制也不是零,默认 release 几 MB 起,启用的插件越多越大。
内存别照搬宣传数字。Tauri 仍要启动系统 WebView 的进程:Windows 上是 msedgewebview2.exe,Linux 上是 WebKit 的进程。每个 Tauri 应用有自己的 WebView 实例,运行时共享不等于进程共享。空页面下 Tauri 通常比 Electron 省,页面复杂、DOM 多时差距会缩小。要比较就在同一台机器、同一个页面、同一个 release 构建下量。
启动速度同理:Rust 启动快,WebView 初始化仍要时间,Windows 冷启动第一次加载 WebView2 可能更慢。另一个坑是 debug 包和 release 包差别很大,拿 tauri dev 的产物比体积没有意义。
迁移:分四步,别一次重写
迁移不是把 Electron 项目改个配置,而是一次结构性改造。前端能复用大部分,外壳和系统能力基本重写。顺序建议如下。
第一步,搬外壳。窗口尺寸、菜单、托盘、单实例、快捷键,先在 tauri.conf.json 和 Rust builder 里还原。菜单 API 在 Tauri 2 里调整过,具体构造方式以当前版本文档为准,待确认。
第二步,搬 IPC。Electron 的 ipcMain.handle 对应 #[tauri::command],preload 的 contextBridge 对应 invoke。想少改前端,可以写一个 bridge.js,保持 window.api 的方法签名不变,内部改成 invoke。这样页面代码几乎不用动,迁移风险集中在一层适配代码里。
第三步,搬系统能力。fs/path 用 std 和 path 插件,http 用 reqwest,child_process 用 shell 插件或 sidecar。Node 原生模块基本没法直接迁,只能找替代或保留 sidecar。每加一个能力,capability 里就多一条权限,别一次性全开。
第四步,搬自动更新。Tauri 有 updater 插件,更新包要签名,公钥写进配置,私钥放 CI。密钥丢了,老用户就收不到升级。具体的环境变量名和配置字段以官方文档为准,待确认。
这四步里,第二步最容易被低估。Electron 的 IPC 是自由格式,Tauri 的 command 有类型约束;原来随手传的对象,现在要定义结构体、处理 Option 和错误。前端调用也从「不会失败」变成「可能 reject」。
什么情况下不该迁
以下情况,迁移的收益可能低于成本。
团队没有 Rust 经验,维护窗口又短。出问题时没人能改,比安装包大几十 MB 麻烦得多。Rust 不是不能学,但要在项目排期里算进去。
依赖大量 Node 原生模块,或者关键库只有 npm 版本。sidecar 能把它们带回来,但等于把 Node 运行时又装了一遍,体积优势消失,还多维护一套进程通信。
需要跨平台完全一致的渲染结果。设计工具、复杂 Canvas/WebGL、像素级排版,依赖的是确定的浏览器版本,系统 WebView 给不了这种确定性。
必须支持 Windows 7/8.1。WebView2 已不在这些系统的支持范围,具体以微软公告为准。还有企业环境要求自带浏览器内核、离线可控、锁定版本,这类需求 Tauri 天然不满足。
现有 Electron 应用很大、测试覆盖差。迁移风险高于收益,先把 Electron 的安全和性能问题修好更实际。还有一种情况:只是嫌安装包大,但用户机器都在受控环境里,WebView2 一定有,这种项目可以先做资源裁剪和依赖清理,未必需要换框架。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 安装后双击没反应或白屏 | 目标机器没有 WebView2 运行时 | 查系统是否安装 WebView2,确认安装器选的是在线引导还是离线包 |
| Linux 上页面错位、样式失效 | WebKitGTK 版本低于开发机 | 执行 pkg-config --modversion webkit2gtk-4.1,和目标发行版最低版本对比 |
| invoke 报 command not found | 命令没注册,或前后端名字不一致 | 看 generate_handler! 列表,核对 invoke 的字符串大小写 |
| invoke 参数反序列化失败 | 类型不匹配,或键名大小写不对 | 对照 Rust 参数类型与前端传来的对象,确认数字没传给 String |
| 调用 fs 插件读文件被拒 | capability 没声明权限,或 scope 不覆盖目标目录 | 查 capabilities/default.json 的 permissions 和 allow path |
| 打包后体积还是很大 | 打进了 node_modules、调试符号,或离线 WebView2 包 | 看 release 产物构成,检查 bundle 配置和资源目录 |
| 内存没比 Electron 少多少 | WebView 进程本身占内存,页面复杂度没变 | 用任务管理器对比两边的进程数和私有内存,别只看应用名 |
| 自动更新失败 | 更新包签名与配置里的公钥不匹配 | 查 updater 配置、签名步骤和发布产物是否一致 |
边界与代价
第一,Rust 的学习曲线和编译时间。首次构建要拉取并编译大量 crate,CI 上更明显;增量编译也不像前端热更新那样即时。团队要接受「改一行 Rust 等一会儿」的节奏。
第二,WebView 差异让测试矩阵变大。以前只需覆盖自己打包的 Chromium,现在要覆盖 Windows 的 WebView2、macOS 的 WKWebView、Linux 的 WebKitGTK,还要覆盖每个平台的最低版本。测试机器和人力都是成本。
第三,Linux 分发碎片化。不同发行版的 WebKitGTK 版本、依赖包名、桌面环境都不一样,打包和验证工作量比 Windows 大。只支持一两个指定发行版,是更现实的选择。
第四,插件生态比 npm 小。缺库就要自己写 command,跨平台适配、权限、错误处理全包。原型阶段觉得什么都有,中后期才发现关键能力要自己补。
第五,权限模型严格,开发时容易「先全开再收紧」。这是人的问题,不是框架的问题,但 Tauri 把权限文件摆在了明面上,评审时更容易发现。上线前一定要逐条核对 capability。
第六,sidecar 会抵消体积优势,更新密钥是单点。把 Node 或 Go 二进制打回来,安装包又大了;签名私钥丢了,更新链路直接断。这两件事都要在选型时想清楚。
第七,大文件不能走一次性序列化。IPC 传几百 MB 的 JSON 会卡住界面、吃掉内存,要改成流式或分块。Rust 侧写起来不难,但这是 Electron 迁移时最容易漏掉的改动。
小结与练习
三句话:Tauri 的体积优势来自复用系统 WebView 和不带 Node,代价是依赖用户机器和一次结构性重写;权限模型默认拒绝,command 里仍要自己校验;迁移按「外壳、IPC、系统能力、更新」四步走,前端能复用,主进程逻辑要重做。
当天可以自己验证的练习:
- 建一个最小项目跑
npm run tauri dev,再跑npm run tauri build,分别量产物大小;拿现有的 Electron 安装包对比,注意区分 debug 和 release。 - 写一个直接调用 fs 插件读文件的按钮,删掉 capability 里的
fs:allow-read-text-file,记录被拒的报错;再加回来并补上 scope,确认只有指定目录可读。 - 给 command 的
String参数传一个数字,观察反序列化错误;再传一个带../的字符串,确认 Rust 侧校验生效。 - 在一台没有 WebView2 的干净 Windows 虚拟机上安装,观察安装器是下载、报错还是跳过;再换离线包模式对比体积。
- 在 Linux 上执行
pkg-config --modversion webkit2gtk-4.1,和开发机、目标发行版的最低版本对比;如果差得远,用那台机器跑一遍主流程。
下一篇讲WebView2 与系统组件集成。Tauri 在 Windows 上落地的关键就是 WebView2:它怎么安装、怎么在 .NET 里直接嵌入、怎么和原生窗口、打印、下载、权限打交道。这一篇讲的是跨框架的结构,下一篇落到 Windows 的具体集成。