tauri-v2

用途

Tauri v2 技能用于构建跨平台桌面与移动应用，前端使用 Web 技术，后端使用 Rust。适用于配置 tauri.conf.json、实现 Rust 命令（#[tauri::command]）、搭建 IPC 通信、设置权限能力以及进行移动端构建等场景。

主要能力

该技能提供可直接套用的代码模式与配置示例，覆盖命令注册、前端调用、权限声明、状态管理、事件发射与 Channel 流式传输等环节。它同时列出常见错误及其根因与解决方案，例如：命令未加入 generate_handler! 导致“Command not found”；缺少 capability 导致“Permission denied”；State<T> 类型不匹配导致访问时 panic；前端未构建导致启动白屏；异步命令阻塞导致 IPC 超时；缺少 Rust target 导致移动端构建失败。

使用方式

快速上手分三步。第一步，在 src-tauri/src/lib.rs 中创建命令并注册：

#[tauri::command]
fn greet(name: String) -> String {
    format!("Hello, {}!", name)
}

pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![greet])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

第二步，从前端调用：

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

const greeting = await invoke<string>('greet', { name: 'World' });
console.log(greeting); // "Hello, World!"

注意使用 @tauri-apps/api/core，而非 v1 的 @tauri-apps/api/tauri。

第三步，添加所需权限（src-tauri/capabilities/default.json）：

{
    "$schema": "../gen/schemas/desktop-schema.json",
    "identifier": "default",
    "windows": ["main"],
    "permissions": ["core:default"]
}

Tauri v2 默认拒绝一切操作，所有操作都需要显式权限。

关键规则

始终：在 tauri::generate_handler![cmd1, cmd2, ...] 中注册每个命令；命令返回 Result<T, E> 以正确处理错误；对多命令共享状态使用 Mutex<T>；在使用任何插件功能前添加 capabilities；将共享代码放在 lib.rs（移动端构建必需）。

避免：在异步命令中使用借用类型（&str），应使用拥有所有权的类型；阻塞主线程，I/O 操作应使用 async；硬编码路径，应使用 Tauri 路径 API（app.path()）；跳过 capability 设置，即使“安全”操作也需要权限。

配置参考

tauri.conf.json 关键设置：build.devUrl 必须与前端开发服务器端口一致；app.security.capabilities 为 capability 文件标识符数组。

Cargo.toml 关键设置：[lib] 段为移动端构建必需；crate-type 必须包含 staticlib、cdylib、rlib 三种类型。

常见模式

错误处理：定义实现 serde::Serialize 的错误枚举，命令返回 Result<String, AppError>。

状态管理：使用 std::sync::Mutex 与 tauri::State，在 builder 中通过 .manage(Mutex::new(AppState { counter: 0 })) 注册。

事件发射：使用 tauri::Emitter，通过 app.emit("task-progress", 50) 发送，前端用 @tauri-apps/api/event 的 listen 监听。

Channel 流式传输：使用 tauri::ipc::Channel，定义带 serde tag/content 的事件枚举，前端用 @tauri-apps/api/core 的 Channel 接收。

依赖

必需：@tauri-apps/cli ^2.0.0、@tauri-apps/api ^2.0.0、tauri ^2.0.0、tauri-build ^2.0.0。

可选插件：tauri-plugin-fs、tauri-plugin-dialog、tauri-plugin-shell、tauri-plugin-http、tauri-plugin-store，均为 ^2.0.0。

适用场景

需要以 Web 前端加 Rust 后端方式开发跨平台桌面或移动应用的场景，尤其是希望减少配置与 IPC 相关常见错误的项目。

限制

资料未提供该技能的具体收费、价格、平台支持范围或效果保证等信息。移动端构建需要安装对应 Rust target，iOS 构建仅限 macOS。