Tauri 插件系统是如何把 Rust 能力暴露给前端的？

Tauri 插件系统的核心作用，是把一组 Rust 能力、前端 API、权限声明和初始化逻辑封装成可复用模块。普通 command 适合项目内一次性能力，插件适合跨项目复用，或者需要在应用启动时注册状态、事件、菜单、后台任务的能力。真正要理解插件，重点不是“怎么写一个函数”，而是它如何在 Rust 侧注册命令，再通过 JavaScript 包提供稳定入口。

插件由哪几部分组成？

一个完整插件通常包含 Rust crate、前端 npm 包、权限配置和示例文档。Rust 侧负责执行系统能力，比如读写文件、调用原生库、管理状态；前端侧只暴露类型友好的函数，不应该让业务代码到处手写 invoke 字符串。这样做的取舍是工程结构变重，但多人项目里更容易控制边界和升级。

bash
pnpm tauri plugin init my-plugin
# 或在 Rust 工具链里使用对应的插件脚手架
cargo install tauri-cli

Rust 侧怎样注册命令？

插件命令仍然是 Tauri command，只是注册在插件命名空间下。下面的例子把一个简单的 greet 暴露出去，真实项目里可以在 setup 里初始化数据库连接、缓存目录或后台 worker。错误类型建议转成字符串或可序列化结构，别把复杂 Rust error 原样丢给前端。

rust
use tauri::{plugin::TauriPlugin, Manager, Runtime};

#[tauri::command]
async fn greet(name: String) -> Result<String, String> {
    if name.trim().is_empty() {
        return Err("name cannot be empty".into());
    }
    Ok(format!("hello, {name}"))
}

pub fn init<R: Runtime>() -> TauriPlugin<R> {
    tauri::plugin::Builder::new("my-plugin")
        .invoke_handler(tauri::generate_handler![greet])
        .setup(|app, _api| {
            let _cache = app.path().app_cache_dir()?;
            Ok(())
        })
        .build()
}

应用里注册插件时要放在 builder 链上，顺序一般不敏感，但依赖某些状态的插件要保证状态先初始化。

rust
fn main() {
    tauri::Builder::default()
        .plugin(my_plugin::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri app");
}

前端 API 为什么要单独封装？

前端封装可以隐藏 plugin:my-plugin|greet 这种字符串协议，也能把参数和返回值写成 TypeScript 类型。业务代码只依赖 greet(name)，以后插件内部从 command 改成事件、缓存或批处理，都不必全局替换。

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

export function greet(name: string): Promise<string> {
  return invoke('plugin:my-plugin|greet', { name });
}

权限和配置放在哪里？

Tauri v2 更强调 capability，插件如果涉及文件、shell、网络或系统通知，必须让应用显式声明权限。这个设计牺牲了一点上手速度，但能避免插件安装后默认拿到过大的系统能力。踩坑最多的是开发阶段 all allow，发布前忘了收紧，导致审核或安全检查不过。

插件如何处理状态和事件？

插件不只适合“一问一答”的 command，也适合维护后台状态。比如文件监听、下载进度、设备连接状态，可以在 Rust 侧运行任务，再通过事件推给前端。这里的边界是不要把插件写成万能全局服务，状态越多，生命周期越难管，窗口关闭、应用退出和权限变化都要处理。

事件名也要当成 API 设计，最好带上插件前缀，避免和业务事件撞名。

配置项也要保持向后兼容，插件升级时不要突然删除字段。更稳的做法是给默认值，并在初始化阶段做版本迁移。

追问

什么时候该写插件，而不是普通 command？

如果能力只在一个应用里用，普通 command 更轻，目录结构也简单。只要它开始被多个项目复用，或者需要配套 npm API、权限、初始化和文档，就值得拆成插件。取舍在于维护成本：插件要考虑版本兼容和发布流程，不能像业务 command 那样随手改签名。

插件能直接访问前端状态吗？

不能把前端状态当成 Rust 里的全局变量来用，插件和 WebView 之间仍然要靠 invoke、事件或状态管理通信。真正需要共享的数据，应放在 Rust managed state、数据库或前端 store 中，并明确谁是数据源。边界是实时 UI 状态不适合塞进插件，系统能力和持久化任务才适合放到 Rust 侧。

插件错误应该怎么返回给前端？

不要只返回 String 然后让前端猜含义，稍复杂的插件可以定义 { code, message } 这样的可序列化错误。这样 UI 可以区分权限不足、参数错误、系统调用失败和用户取消。踩坑点是 Rust error 很丰富，但跨 IPC 后只能传可序列化数据，错误设计太随意会让前端无法做可靠提示。

官方插件和自研插件怎么选？

文件、对话框、通知、剪贴板这类通用能力优先用官方插件，因为权限模型和跨平台细节有人维护。自研插件适合业务协议、公司内部 SDK、特殊硬件或性能敏感的原生能力。取舍是官方插件稳定但不一定覆盖细节，自研插件灵活但要自己承担测试矩阵。

插件发布到 npm 和 crates.io 要注意什么？

前端包和 Rust crate 的版本最好同步，否则用户会遇到 JS API 已升级、Rust 插件没升级的错位问题。发布前要固定最低 Tauri 版本，并写清楚需要哪些 capability 权限。最容易踩坑的是只测示例项目，不测从空项目安装后的真实路径和打包结果。