Tauri Plugins

Tauri 插件开发与集成

当前项目已安装插件

Cargo 依赖（src-tauri/Cargo.toml）

[dependencies]
tauri = { version = "2", features = [] }
tauri-plugin-opener = "2"
tauri-plugin-store = "2"
tauri-plugin-log = "2"
tauri-plugin-updater = "2"
tauri-plugin-process = "2"

已注册插件（src-tauri/src/lib.rs）

pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_opener::init())
        .plugin(tauri_plugin_store::Builder::new().build())
        .plugin(tauri_plugin_log::Builder::new().build())
        .plugin(tauri_plugin_updater::Builder::new().build())
        .plugin(tauri_plugin_process::init())
        .invoke_handler(tauri::generate_handler![...])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

已配置权限（src-tauri/capabilities/default.json）

{
  "permissions": [
    "core:default",
    "opener:default",
    "store:default",
    "log:default",
    "updater:default",
    "process:default"
  ]
}

官方插件完整清单

核心功能插件

数据存储插件

注意: 本项目使用 rusqlite 直接操作 SQLite，而非 tauri-plugin-sql。

系统交互插件

插件初始化方式速查

插件集成 3 步法（适配三层架构）

步骤 1: 安装依赖

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-fs = "2"

pnpm add @tauri-apps/plugin-fs

步骤 2: 注册插件

// src-tauri/src/lib.rs
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_opener::init())
        .plugin(tauri_plugin_store::Builder::new().build())
        .plugin(tauri_plugin_log::Builder::new().build())
        .plugin(tauri_plugin_fs::init())    // 新增
        .invoke_handler(tauri::generate_handler![...])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

步骤 3: 声明权限

// src-tauri/capabilities/default.json
{
  "permissions": [
    "core:default",
    "opener:default",
    "store:default",
    "log:default",
    "fs:default",              // 新增
    "fs:allow-read-text-file"  // 新增（细粒度权限）
  ]
}

在三层架构中使用插件

插件功能应遵循项目的三层架构（Database/Service/Command），避免在 Command 层直接堆砌业务逻辑。

方式一：插件功能封装到 Service 层

适用于大多数插件（shell、os、dialog、notification 等），插件提供的能力作为业务逻辑的一部分。

// ── Service 层封装插件逻辑 ──
// src-tauri/src/services/system.rs
use crate::error::AppError;

/// 获取系统信息（封装 os 插件或 std 能力）
pub fn get_system_info() -> Result<SystemInfo, AppError> {
    Ok(SystemInfo {
        platform: std::env::consts::OS.to_string(),
        arch: std::env::consts::ARCH.to_string(),
    })
}

// ── Command 层暴露给前端 ──
// src-tauri/src/commands/system.rs
#[tauri::command]
pub fn get_system_info() -> Result<SystemInfo, String> {
    crate::services::system::get_system_info()
        .map_err(|e| e.to_string())
}

方式二：需要 AppHandle 的插件

某些插件 API 需要 AppHandle（如 notification、dialog、updater），通过 Command 参数注入。

// ── Command 层（注入 AppHandle）──
#[tauri::command]
pub async fn check_update(app: tauri::AppHandle) -> Result<bool, String> {
    crate::services::update::check_for_update(&app)
        .await
        .map_err(|e| e.to_string())
}

// ── Service 层（接收 AppHandle 引用）──
// src-tauri/src/services/update.rs
pub async fn check_for_update(app: &tauri::AppHandle) -> Result<bool, AppError> {
    let update = app.updater_builder().build()
        .map_err(|e| AppError::Custom(e.to_string()))?
        .check()
        .await
        .map_err(|e| AppError::Custom(e.to_string()))?;
    Ok(update.is_some())
}

方式三：前端直接使用插件 JS API

某些插件支持前端直接调用，无需经过 Rust Command（适用于简单场景）。

// 前端直接使用 store 插件
import { Store } from "@tauri-apps/plugin-store";
const store = new Store("settings.json");
await store.set("theme", "dark");

// 前端直接使用 opener 插件
import { open } from "@tauri-apps/plugin-opener";
await open("https://example.com");

// 前端直接使用 process 插件
import { exit, relaunch } from "@tauri-apps/plugin-process";
await relaunch();

决策指南：Rust Command vs 前端 JS API

自定义 Tauri 插件

插件结构

use tauri::plugin::{Builder, TauriPlugin};
use tauri::Runtime;

// 定义插件命令
#[tauri::command]
fn my_plugin_command() -> String {
    "Hello from plugin!".into()
}

// 构建插件
pub fn init<R: Runtime>() -> TauriPlugin<R> {
    Builder::new("my-plugin")
        .invoke_handler(tauri::generate_handler![my_plugin_command])
        .build()
}

注册自定义插件

// src-tauri/src/lib.rs
mod my_plugin;

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

前端调用

// 自定义插件的命令通过 invoke 调用
const result = await invoke("plugin:my-plugin|my_plugin_command");

项目数据存储策略

本项目采用双数据存储方案：

tauri-plugin-store 使用示例

// 前端直接使用
import { Store } from "@tauri-apps/plugin-store";

const store = new Store("settings.json");
await store.set("theme", "dark");
const theme = await store.get<string>("theme");

rusqlite 使用示例

// 在三层架构中使用
// database/user.rs
use rusqlite::{Connection, Result};
use crate::models::User;

pub fn get_user(conn: &Connection, id: i64) -> Result<User, rusqlite::Error> {
    conn.query_row(
        "SELECT id, name FROM users WHERE id = ?1",
        [id],
        |row| Ok(User {
            id: row.get(0)?,
            name: row.get(1)?,
        })
    )
}

// services/user.rs
use crate::database;
use crate::error::AppError;

pub fn fetch_user(id: i64) -> Result<User, AppError> {
    let conn = get_connection()?;
    Ok(database::user::get_user(&conn, id)?)
}

// commands/user.rs
#[tauri::command]
pub fn get_user(id: i64) -> Result<User, String> {
    crate::services::user::fetch_user(id)
        .map_err(|e| e.to_string())
}

排查插件问题

常见错误