tauri

Tauri

概述

Tauri 是一个用于构建桌面和移动应用的框架，使用 Web 技术（HTML、CSS、JavaScript/TypeScript）构建 UI，使用 Rust 编写后端逻辑。它利用操作系统的 Webview，而不是捆绑浏览器引擎，因此生成的二进制文件体积小、速度快。IPC 层通过基于能力的权限系统，将前端连接到 Rust 命令。

适用场景： 带 Web UI 的跨平台桌面／移动应用、系统级集成（托盘、通知、文件系统）、需要较小安装包的应用，以及需要精细权限控制的安全敏感型应用。

不适用场景： 没有原生功能需求的纯 Web 应用；严重依赖 Node.js API 且没有迁移到 Rust 的路径的 Electron 应用；团队没有能力维护 Rust 代码的项目。

快速参考

模式	API / 配置	要点
创建项目	cargo create-tauri-app 或 pnpm create tauri-app	搭建 Rust 后端和前端框架
定义命令	#[tauri::command] fn name() {}	必须在 generate_handler! 中注册
从前端调用	invoke('cmd_name', { arg: value })	返回 Promise，参数使用 camelCase JSON
发送事件（前端）	emit('event-name', payload)	全局事件，所有监听器都会收到
监听事件	listen('event-name', handler)	返回取消监听函数
管理状态	app.manage(MyState {}) + State<'_, MyState>	无需 Arc；需要可变性时使用 Mutex
创建窗口	WebviewWindowBuilder::new(app, label, url)	每个窗口的标签必须唯一
系统托盘	TrayIconBuilder::new().menu(&menu).build(app)	需要启用 Cargo 的 tray-icon 功能
添加插件（Rust）	.plugin(tauri_plugin_name::init())	在 Builder 调用链中注册
添加插件（前端）	@tauri-apps/plugin-name	每个插件对应一个 NPM 包
定义能力	src-tauri/capabilities/*.json	限定到特定窗口，并在构建时合并
授予权限	"permissions": ["plugin:scope"]	未明确授予权限时，无法访问命令
Sidecar 二进制文件	tauri.conf.json bundle.externalBin	名称必须与 {name}-{target_triple} 匹配
自定义协议	tauri::Builder::default().register_uri_scheme_protocol	拦截自定义 scheme:// URL
自动更新	tauri-plugin-updater + JSON endpoint	需要代码签名
应用打包／签名	cargo tauri build	通过环境变量进行平台专属签名

常见错误

错误	正确做法
多次调用 generate_handler!	将所有命令传递给同一次 generate_handler! 调用
在异步命令参数中使用 &str	在异步命令中使用所有权型 String 类型
忘记为插件添加 capability	在 src-tauri/capabilities/*.json 中添加权限标识符
将状态封装在 Arc 中	Tauri State 会在内部处理引用计数
在 .await 位置之间使用 std::sync::Mutex	对跨越多个 await 的持锁异步命令使用 tokio::sync::Mutex
sidecar 二进制文件名称错误	二进制文件必须命名为 {name}-{target_triple}（例如，mybin-x86_64-pc-windows-msvc）
假设所有窗口共享 capability	每个窗口/webview 都有按标签限定的 capability
使用 SystemTray（v1 API）	在 v2 中使用 tauri::tray 模块中的 TrayIconBuilder
启用 updater 前未对应用签名	自动更新器要求所有平台都具有有效的代码签名
使用窗口标题进行安全决策	capability 使用窗口的标签，而非标题

委派

• 命令模式探索：使用 Explore Agent
• 安全审查：使用 Task Agent
• 代码审查：委派给 code-reviewer Agent

如果有 rust 技能，请将 Rust 语言模式、错误处理和异步/并发任务委派给它。 如果有 react-patterns 技能，请将 React 前端模式委派给它。 如果有 svelte 技能，请将 Svelte 前端模式委派给它。 如果有 vite 技能，请将构建工具和开发服务器配置委派给它。 如果有 github-actions 技能，请将 CI/CD 流水线和发布工作流配置委派给它。

参考

• 项目设置、配置和目录结构
• IPC 命令、事件和通道
• 状态管理模式
• 窗口管理和多窗口应用
• 系统托盘和菜单
• 插件系统和官方插件
• 安全模型、capability 和权限
• sidecar 二进制文件和自定义协议
• 应用签名、分发和自动更新