第一次搭 Tauri 的人,八成会在同几个地方卡住:命令跑了一半提示找不到 tauri;窗口起来了但一片白;前端点了按钮,Rust 那边一点反应都没有;或者开发模式一切正常,打包以后界面直接空白。这些问题看起来分散,其实都指向同一件事:Tauri 不是「Rust 版 Electron」,它是一个把前端资源和原生窗口拼起来的框架,你得知道每一块放在哪、谁来读它。

这篇的目标很具体:让你把一个小窗口跑起来,并且能解释清楚「窗口标题从哪来、按钮点下去调用了谁、数据怎么回到界面」。至于打包发布,留到后面几篇。本文按 Tauri 2 讲,示例结构对应 2.x 的标准模板;Windows 上的运行时前提在上一篇已经验证过,这里不再重复。

先看它由什么组成

一个 Tauri 工程的运行结构可以分成三层。最上面是 WebView 里的前端页面,就是普通的 HTML、CSS、JavaScript,可以用任何前端框架,也可以完全不用框架。中间是 Tauri 注入到页面里的 IPC 接口,前端通过 invoke 调用 Rust 命令,Rust 通过事件把消息推回页面。最下面是 Rust 进程,负责创建窗口、读文件、访问系统能力,也是最终被编译成可执行文件的那部分。

前端:HTML 与 JavaScript,运行在系统 WebView 里,负责显示和交互
IPC:invoke 命令与事件,负责前后端之间的请求、响应和推送
Rust 核心:窗口创建、文件访问、系统集成,编译进最终的可执行文件

为什么它比自带浏览器的方案小?因为浏览器内核不在安装包里,用的是系统已经装好的 WebView。Windows 用 WebView2,macOS 用 WKWebView,Linux 用 WebKitGTK。安装包里主要是你的前端资源、Rust 编译出的可执行文件,以及少量配置。代价是运行环境不再由你完全控制:系统里的 WebView 版本太旧、被禁用或者缺失,程序就起不来。

也正因为内核是系统提供的,同一个工程在不同平台上的安装包大小和启动表现会差不少。Windows 上你几乎不用为内核付出体积,但要处理「没装 WebView2」;Linux 上很多发行版需要把 WebKitGTK 的相关库一起带上,包体反而会明显变大;macOS 的系统版本决定了 WKWebView 的能力上限。写发布说明时,最好按平台分别写清楚依赖,而不是给一句笼统的「需要现代操作系统」。

一个最小工程长什么样

用官方脚手架创建工程后,目录大致如下。不同前端模板的文件名会变,但结构是固定的:根目录放前端,src-tauri 放 Rust 和配置。

rename-tool/
  package.json
  index.html
  src/main.js
  src-tauri/
    Cargo.toml
    tauri.conf.json
    capabilities/default.json
    src/lib.rs
    src/main.rs
    icons/

几个容易搞混的点先说明白。src-tauri/Cargo.toml 是 Rust 的依赖清单,不是前端的;tauri.conf.json 是窗口、构建命令和打包目标的配置;capabilities/default.json 是 Tauri 2 引入的权限文件,前端能调用哪些接口要在这里授权;src/main.rs 通常只有几行,真正的内容在 lib.rs,这样做是为了让桌面端和移动端共享同一套逻辑。

脚手架命令有两种,效果一样:

npm create tauri-app@latest
cargo create-tauri-app

如果你只想要最小的东西,选「无框架」的前端模板即可,生成出来的就是原生 HTML 加一个 main.js,没有构建步骤,理解起来最省事。等结构看明白了,再换成 Vue、React 或 Svelte 都不迟。

配置文件负责什么

tauri.conf.json 是整套配置里最需要先读一遍的文件。下面是一个能用的最小版本,字段按 Tauri 2 的写法:

{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "rename-tool",
  "version": "0.1.0",
  "identifier": "cn.example.rename",
  "build": {
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:1420",
    "beforeBuildCommand": "npm run build",
    "frontendDist": "../dist"
  },
  "app": {
    "windows": [
      {
        "title": "素材重命名",
        "width": 900,
        "height": 600,
        "resizable": true
      }
    ],
    "security": {
      "csp": null
    }
  },
  "bundle": {
    "active": true,
    "targets": "all"
  }
}

几个字段的实际作用:productName 决定安装后的程序名;identifier 是系统里区分应用的唯一标识,升级和配置目录都依赖它,发布以后不要再改;build.devUrl 是开发时前端开发服务器地址,frontendDist 是打包时前端产物目录;app.windows 里写窗口的初始标题和尺寸;bundle.targets 决定生成哪些安装格式。

identifier 不要用默认的 com.tauri.dev,也不要带下划线或中文。它在 Windows 上参与应用标识和部分系统路径的生成,改一次等于换了一个应用,旧配置和旧升级记录都对不上。

开发时最常见的白屏,和 devUrl 写错、前端开发服务器没启动、或者端口被占用直接相关。判断顺序是:先看终端里前端服务器有没有真的在监听,再打开浏览器访问那个地址能不能看到页面,最后才怀疑 Tauri。如果浏览器能打开、Tauri 窗口是白的,问题通常在构建产物路径,而不是前端代码。

Rust 侧:命令与状态

Rust 侧的入口在 lib.rs。下面这个版本提供一个重命名计划命令,并演示怎么用 State 保存跨请求的状态:

use serde::Serialize;
use std::sync::Mutex;
use tauri::State;

#[derive(Serialize)]
struct PlanItem {
    old: String,
    new: String,
}

struct AppState {
    last_dir: Mutex<String>,
}

#[tauri::command]
fn plan_rename(dir: String, prefix: String, state: State<AppState>) -> Result<Vec<PlanItem>, String> {
    let mut files: Vec<std::path::PathBuf> = std::fs::read_dir(&dir)
        .map_err(|err| format!("读取目录失败: {}", err))?
        .filter_map(|entry| entry.ok())
        .map(|entry| entry.path())
        .filter(|path| path.is_file())
        .collect();
    files.sort();

    let mut items = Vec::new();
    for (index, path) in files.iter().enumerate() {
        let old = path.file_name().unwrap().to_string_lossy().to_string();
        let ext = path
            .extension()
            .map(|value| value.to_string_lossy().to_string())
            .unwrap_or_default();
        let new = if ext.is_empty() {
            format!("{}_{:03}", prefix, index + 1)
        } else {
            format!("{}_{:03}.{}", prefix, index + 1, ext)
        };
        items.push(PlanItem { old, new });
    }

    *state.last_dir.lock().unwrap() = dir;
    Ok(items)
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .manage(AppState {
            last_dir: Mutex::new(String::new()),
        })
        .invoke_handler(tauri::generate_handler![plan_rename])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

这段代码里有三个关键点。第一,命令函数用 #[tauri::command] 标记,参数和返回值要能被序列化,返回 Result 时错误类型要能转成前端看得懂的字符串。第二,State<AppState> 由框架注入,不需要自己创建;注册时用 .manage() 放进去。第三,generate_handler! 里列出的命令名,就是前端调用时用的名字,漏写一个就会得到「命令未找到」。

Cargo.toml 里至少要这几项:

[dependencies]
tauri = { version = "2", features = [] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

[build-dependencies]
tauri-build = { version = "2", features = [] }

src/main.rs 只负责调用库里的 run:

#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

fn main() {
    rename_tool_lib::run();
}

那行 windows_subsystem 的作用是发布版不弹控制台窗口。开发时保留控制台,日志能直接看到;发布时去掉,否则用户双击以后会多出一个黑框。

前端侧:调用与权限

前端调用 Rust 命令,Tauri 2 的导入路径是 @tauri-apps/api/core:

import { invoke } from "@tauri-apps/api/core";

const dir = document.querySelector("#dir").value;
const prefix = document.querySelector("#prefix").value;

try {
  const items = await invoke("plan_rename", { dir, prefix });
  const list = document.querySelector("#list");
  list.innerHTML = "";
  for (const item of items) {
    const row = document.createElement("li");
    row.textContent = `${item.old} -> ${item.new}`;
    list.appendChild(row);
  }
} catch (err) {
  document.querySelector("#status").textContent = `失败: ${err}`;
}

参数名要和 Rust 函数的参数名对上。Rust 里叫 dir,前端就传 dir,不是 directory。返回值是一个数组,字段名来自 PlanItem 的字段,序列化后就是普通的 JavaScript 对象。错误会进入 catch,内容就是你 Result 里返回的那个字符串。

Tauri 2 的权限文件决定前端能调用哪些内置接口。自定义命令默认可用,但如果你用了文件系统、对话框、Shell 这类插件,就必须在 capabilities/default.json 里声明,否则运行时会报「不允许」。最小配置通常是这样:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "默认窗口权限",
  "windows": ["main"],
  "permissions": ["core:default"]
}

权限报错不会在编译期出现,只会在运行时冒出来,所以第一次接插件时,先把控制台打开,看清楚是「命令不存在」还是「权限被拒」,这两个错误的处理方向完全不同。

本机实测用的是一条更小的命令:Rust 侧写一个 #[tauri::command] fn greet(name: &str) -> String,前端在 withGlobalTauri 打开的情况下直接调 window.__TAURI__.core.invoke('greet',{name:'科设'}),同一进程内往返 7.9 毫秒。这个时间包含参数序列化、IPC 传输、命令执行和回调兑现,比一次普通的文件读取还快,说明 IPC 本身通常不是瓶颈。真正让界面变慢的,往往是你在命令里同步做的事,而不是这条消息走了多久。

顺带说明为什么这里用 window.__TAURI__.core.invoke,而不是上面的 import 写法:在 tauri.conf.json 里把 app.withGlobalTauri 设为 true 以后,Tauri 会把接口挂到全局对象上,页面不经过前端构建也能直接调。它适合验证链路和排查问题,正式项目仍然建议用模块导入,这样打包器能做类型检查和摇树优化。两种写法调的是同一套命令,7.9 毫秒这个往返时间对两者都成立。

本机实测边界与替代验证

需要如实交代实测范围:这台机器上 rustc、cargo、node 都可用,Tauri CLI 2.12.4 也已经装好。tauri build --no-bundle 真跑过一次,从头编译用了 3 分 40 秒,产物 app.exe 为 8,746 KB,也就是 8.5 MB。启动用 WaitForInputIdle 测到 67 到 68 毫秒,工作集 25.1 MB。打开 withGlobalTauri 后,前端执行 window.__TAURI__.core.invoke('greet',{name:'科设'}),同一进程内往返 7.9 毫秒。这些都是本机实际数字,不是估出来的。

打包这一半却卡住了。执行完整的 tauri build,进到 NSIS 阶段报 failed to bundle project: 拒绝访问。 (os error 5);原样重试一次仍是同样错误,按提示预先创建 %LOCALAPPDATA%\tauri 目录后再试,还是失败。所以安装包体积、安装后的快捷方式、卸载行为和首次启动仍是未验证的。这篇文章能负责的范围到「编译出 exe 并启动」为止,安装包那一段只写步骤,不给数字。

第一步,确认运行时前提。用上一篇的 webview2_check 查版本,本机输出是 HKLM -> 156.0.4314.58,说明系统级 WebView2 存在。第二步,确认工具链:

rustc --version
cargo --version
node --version
npx @tauri-apps/cli --version

这四条在本机都有输出,最后一条是 2.12.4。如果你的机器上还没有 CLI,用 npx 调本地版本即可,不要把「命令不存在」当成 Rust 环境的问题。第三步,把前端部分单独放到浏览器里跑,确认界面和事件绑定没问题。第四步,用下面的命令分发器理解 invoke 到底做了什么。

这是一个只用标准库实现的迷你分发器,读一行请求,返回一行 JSON。它模拟的正是「前端发命令、Rust 匹配命令名、返回结果」这条链路:

use std::collections::HashMap;
use std::io::{self, BufRead};

struct State {
    map: HashMap<String, String>,
}

fn handle(state: &mut State, line: &str) -> String {
    let mut parts = line.split_whitespace();
    let cmd = parts.next().unwrap_or("");
    let args: Vec<&str> = parts.collect();
    match cmd {
        "ping" => r#"{"ok":true,"data":"pong"}"#.to_string(),
        "set" if args.len() == 2 => {
            state.map.insert(args[0].to_string(), args[1].to_string());
            format!(
                r#"{{"ok":true,"data":{{"key":"{}","value":"{}"}}}}"#,
                args[0], args[1]
            )
        }
        "get" if args.len() == 1 => match state.map.get(args[0]) {
            Some(value) => format!(r#"{{"ok":true,"data":"{}"}}"#, value),
            None => r#"{"ok":false,"error":"not found"}"#.to_string(),
        },
        _ => format!(r#"{{"ok":false,"error":"bad command: {}"}}"#, cmd),
    }
}

fn main() {
    let mut state = State { map: HashMap::new() };
    let stdin = io::stdin();
    for line in stdin.lock().lines() {
        let line = line.unwrap();
        let line = line.trim();
        if line.is_empty() {
            continue;
        }
        println!("[req]  {}", line);
        println!("[resp] {}", handle(&mut state, line));
    }
    println!("[done] state keys = {}", state.map.len());
}
rustc -O mini_router.rs
"ping`nset theme dark`nget theme`nget missing`nelbow" | .\mini_router.exe
[req]  ping
[resp] {"ok":true,"data":"pong"}
[req]  set theme dark
[resp] {"ok":true,"data":{"key":"theme","value":"dark"}}
[req]  get theme
[resp] {"ok":true,"data":"dark"}
[req]  get missing
[resp] {"ok":false,"error":"not found"}
[req]  elbow
[resp] {"ok":false,"error":"bad command: elbow"}
[done] state keys = 1

真实 Tauri 的 invoke 多了序列化、线程调度和权限检查,但骨架就是这个:命令名匹配、参数解析、状态保存、结果或错误返回。理解了这个模型,再去看「命令未找到」「返回类型不匹配」这类报错,就不会一头雾水。

回到 Tauri 工程本身,本机这条构建链路的真实顺序是:npx tauri build --no-bundle 先跑前端构建,再让 cargo 以 release 配置编译 Rust 侧和所有依赖,整段耗时 3 分 40 秒,最后产出 src-tauri/target/release/app.exe,大小 8,746 KB。这个 exe 不含 WebView2,运行时用的是系统里已有的 156.0.4314.58。启动之后,用 WaitForInputIdle 等到窗口可交互,测到 67 到 68 毫秒;同一时刻看进程工作集是 25.1 MB。这两个数字比「网页壳」的常见印象低,原因是内核没打进包,启动时也不需要解压前端资源。

把 --no-bundle 去掉,构建会继续走 NSIS,然后停在那个 os error 5。这个错误不是 Rust 编译错误,也不是前端构建错误,而是打包器在写临时文件或调用 makensis 时被拒绝访问。常见来源是杀毒软件、受控目录权限,或者 %LOCALAPPDATA% 下的缓存目录不可写。本机重试和预建目录都没有解决,所以只能把这一项标成未验证。你要在自己机器上继续,建议先单独跑一次 npx tauri build,看错误具体出在哪一步,再决定是改缓存目录还是换权限。不要因为打包失败就怀疑前面的代码。

从需求到跑起来:完整走查

假设还是要做那个素材重命名工具,用 Tauri 的完整顺序如下。每一步都能单独验收,不要跳步。

Tauri 工具的开发顺序
确认 WebView2 与工具链版本
生成最小工程并跑起空窗口
把核心逻辑写成命令并在命令行侧验证
前端接上命令,用一个真实目录走一遍
打包后在干净机器上复验

第二步的验收标准是窗口能显示指定标题和尺寸,不是「终端没报错」。第三步的验收标准是命令对异常目录、空目录、中文名都能返回可读结果。第四步的验收标准是点按钮后界面不假死,列表能滚动,错误能显示在界面上。第五步的验收标准是安装包在没装开发工具的机器上能启动,并且能找到前端资源。

这个顺序里最容易省掉的是第三步。很多人直接把逻辑写进命令函数,然后在界面上点来点去调试。界面一卡,你分不清是逻辑慢、IPC 序列化慢,还是前端渲染慢。把逻辑先做成纯函数、用命令行喂数据,能把范围缩小一半。

按本机的数字,第二步「跑起空窗口」之后可以先记一笔:从 WaitForInputIdle 到窗口可交互是 67 到 68 毫秒,工作集 25.1 MB;第四步接上命令后,invoke 往返 7.9 毫秒。把这两个基线写进项目笔记,后面界面变卡、启动变慢时,你才有一个明确的对照物,而不是凭印象说「好像比以前慢」。

出了问题先看哪里

现象真实原因第一步查什么
终端提示找不到 tauri 命令CLI 没装,或只装在前端项目的本地依赖里看 package.json 的脚本;用 npx 调本地版本
窗口白屏,终端无报错前端开发服务器没起,或 devUrl 端口不对浏览器访问那个地址;看终端端口占用
打包后白屏,开发时正常frontendDist 指错,或构建产物没生成解开安装包看资源目录;先手动跑一次前端构建
invoke 报命令不存在命令没进 generate_handler!,或名字拼错对照 Rust 函数名和前端字符串
invoke 报权限被拒用了插件接口但 capabilities 没声明看控制台错误里的权限标识;补对应 permission
参数传过去是 undefined前后端参数名不一致,或没有 camelCase 转换打印 Rust 收到的参数;检查前端对象键名
程序启动就退出,没有窗口WebView2 缺失,或 identifier 非法查 WebView2 注册表;改用合法 identifier 重试
tauri build 停在 NSIS 阶段,报 os error 5打包器写缓存或调用 makensis 时被拒绝访问看完整错误行;检查 %LOCALAPPDATA% 权限与杀毒拦截

边界与代价

Tauri 的优势是省掉浏览器内核的体积,并且让前端技能直接复用。但它把复杂度转移到了另外几个地方:一是运行时依赖,用户机器上的 WebView 版本你控制不了;二是权限模型,Tauri 2 的 capabilities 比早期版本严格,插件接口要逐个声明;三是跨平台差异,Windows 的窗口装饰、macOS 的菜单栏、Linux 的 WebKitGTK 版本,都会让「同一份代码」出现不同表现。

还有一个现实问题:前端资源仍然是网页。如果界面用了很重的框架、很大的图标库,启动时还是要解析和渲染,体积也会回到十几兆。Tauri 能让安装包从两百兆降到十几兆,但不会把网页应用的启动开销变成零。真正需要「秒开」的场景,还是得看原生窗口路线。本机的 Tauri 产物是 8,746 KB。这个数字只包含 exe 本身:前端资源嵌在里面,WebView2 用的是系统已有的运行时,没有单独带内核。所以它既不能和「安装包大小」混为一谈,也不能和「装完之后的磁盘占用」混为一谈。想把体积压得更低,第一步不是调编译参数,而是确认资源文件有没有重复打包、有没有把开发依赖带进来。

判断要不要用 Tauri,可以问三个问题:目标机器是否都有可用的 WebView?团队是否愿意维护一套前端代码?界面是否以表单、列表、图表为主?三个都答是,Tauri 通常是最省时间的选择;有一个答否,就该考虑原生窗口或者换方案。

当天能验证的练习

  1. 用 mini_router 加一个 del 命令,删除一个键,验证不存在时的错误返回。
  2. 把上面 plan_rename 的逻辑抽成纯函数,用命令行喂三个不同目录,记录异常输入的表现。
  3. 在浏览器里单独打开你的前端页面,用一个假的 invoke 函数替换真实调用,确认界面渲染和错误提示都正常。
  4. 安装 CLI 后生成一个空工程,只改窗口标题和尺寸,确认改的是 tauri.conf.json 而不是 index.html;再跑一次 tauri build --no-bundle,记录编译耗时和 app.exe 体积。
  5. 把 identifier 改成一个带大写字母的值,观察构建是否报错,理解合法标识的约束。

窗口跑起来只是开始。下一步是把「前端调用、后台处理、结果回传」这条链路做稳:同一个界面上的多个请求怎么区分、慢任务怎么不阻塞界面、共享状态怎么避免读到旧值。下一篇就专门讲 IPC 与状态管理,用的还是这套命令模型,但会把并发和顺序问题摆到台面上。