夜雨聆风起因：Tauri 生态里找不到好用的统计插件
事情是这样的。我有一堆 Tauri v2 的桌面应用（护眼卫士、电脑资源监控、电脑搜索等等），上线之后想知道用户到底在用哪些功能、留存怎么样。这种需求在 Web 世界太常见了——接入个 Google Analytics 或者 Mixpanel 就完事。但桌面应用不一样，尤其是 Tauri 的生态还比较年轻，翻了一圈 GitHub，能用的遥测插件真不多。
然后我发现了 Aptabase。
Aptabase 是一个开源的、隐私优先的应用分析平台，专门给桌面和移动端用的，有 Tauri SDK。设计思路我很喜欢——不搞那些花里胡哨的用户画像，只收集最基础的事件和系统信息，GDPR 合规。但问题来了：Aptabase 的 Tauri 插件绑死了它自己的后端，如果你想用别的分析后端，或者自己搭一个，就得魔改。
于是我做了一个决定：参考 Aptabase 的设计思路，但从零写一个后端无关的 Tauri 插件。你可以把它指向任何实现了相同 ingest 协议的后端——Aptabase 自己的、你自己搭的、甚至是一个简单的 Hono + Supabase 都行。
这就是 tauri-plugin-telemetry 的由来。
这篇文章带你走一遍整个插件的实现过程。如果你也想给 Tauri 写插件，或者想了解一个 Rust 插件的内部是怎么工作的，这篇应该对你有用。
Tauri v2 插件长什么样？
在动手之前，先搞清楚 Tauri v2 的插件机制。跟 v1 比，v2 的插件系统规范多了。一个 Tauri 插件本质上就是一个 Rust crate，加上可选的 JavaScript 绑定。
最精简的结构：
tauri-plugin-telemetry/├── Cargo.toml # Rust crate 配置├── build.rs # 告诉 Tauri 有哪些 command├── src/│ ├── lib.rs # 插件入口│ ├── builder.rs # Builder 模式配置│ ├── client.rs # 核心客户端逻辑│ ├── commands.rs # 暴露给前端的 IPC 命令│ ├── config.rs # 配置解析│ ├── dispatcher.rs # 事件队列 + HTTP 发送│ ├── session.rs # 会话管理│ └── sys.rs # 系统信息采集├── webview-src/│ └── index.ts # 前端 JS/TS 绑定└── permissions/ # Tauri v2 的权限控制先看 build.rs，这是最简单的一块：
const COMMANDS: &[&str] = &["track_event"];fn main() { tauri_plugin::Builder::new(COMMANDS).build();}就这么多。build.rs 的作用是告诉 Tauri 的构建系统："这个插件暴露了哪些 command"。Tauri 会根据这个自动生成权限相关的代码——在 permissions/ 目录下你会看到自动生成的 track_event.toml，定义了 allow-track-event 和 deny-track-event 两个权限。
这是 Tauri v2 的安全模型：前端默认不能调用任何插件命令，必须在 capabilities 文件里显式声明权限。这一点跟 Electron 的"默认全开"完全不同。
插件入口：怎么把自己注册进 Tauri
src/lib.rs 是插件的入口。核心就做两件事：提供一个 init 函数，实现 EventTracker trait。
mod builder;mod client;mod commands;mod config;mod dispatcher;mod session;mod sys;use std::sync::Arc;use std::time::Duration;pub use builder::{Builder, PanicHook};use client::TelemetryClient;use serde_json::Value;use tauri::{App, AppHandle, Manager, Runtime, Window};/// 快捷方式：Builder::new(app_key).build() 的语法糖pub fn init<R: Runtime>(app_key: &str) -> tauri::plugin::TauriPlugin<R> { Builder::new(app_key).build()}用户注册插件就一行代码：
tauri::Builder::default() .plugin(tauri_plugin_telemetry::init("APP_KEY")) .run(tauri::generate_context!()) .expect("error while running tauri application");然后是 EventTracker trait——这是给 Rust 端用的 API：
pub trait EventTracker { fn track_event(&self, name: &str, props: Option<Value>) -> Result<(), String>; fn flush_events_blocking(&self);}macro_rules! impl_event_tracker { ($($t:ty),*) => { $( impl EventTracker for $t { fn track_event(&self, name: &str, props: Option<Value>) -> Result<(), String> { let client = self.state::<Arc<TelemetryClient>>(); client.track_event(name, props) } fn flush_events_blocking(&self) { let client = self.state::<Arc<TelemetryClient>>(); client.flush_blocking() } } )* };}impl_event_tracker!(App, AppHandle, Window);这里用了个宏给 App、AppHandle、Window 三个类型都实现了 EventTracker。这样用户在 Tauri 的任何生命周期阶段都能发事件：
// 在 setup 里app.track_event("app_started", None);// 在 RunEvent 里handler.track_event("app_exited", None);handler.flush_events_blocking();说实话，这个宏的设计我是从 Aptabase 的源码里学来的，但我觉得它比手动给每个类型写 impl 要干净多了。宏在 Rust 里经常被滥用，但这种"给一组类型统一实现同一个 trait"的场景，宏是正解。
Builder 模式：让用户配置插件
src/builder.rs 是插件的配置入口。我用了经典的 Builder 模式：
pub struct Builder { app_key: String, panic_hook: Option<PanicHook>, options: InitOptions,}impl Builder { pub fn new(app_key: &str) -> Self { Self { app_key: app_key.into(), panic_hook: None, options: Default::default(), } } pub fn with_host(mut self, host: impl Into<String>) -> Self { self.options.host = Some(host.into()); self } pub fn with_options(mut self, opts: InitOptions) -> Self { self.options = opts; self } pub fn with_panic_hook(mut self, hook: PanicHook) -> Self { self.panic_hook = Some(hook); self } pub fn build<R: Runtime>(self) -> TauriPlugin<R> { plugin::Builder::new("telemetry") .invoke_handler(tauri::generate_handler![commands::track_event]) .setup(|app, _api| { let cfg = Config::new(self.app_key, self.options); let app_version = app.package_info().version.to_string(); let client = Arc::new(TelemetryClient::new(&cfg, app_version)); client.start_polling(cfg.flush_interval); if let Some(hook) = self.panic_hook { install_panic_hook(hook, client.clone()); } app.manage(client); Ok(()) }) .on_event(move |app, event| { if let RunEvent::Exit = event { let client = app.state::<Arc<TelemetryClient>>(); client.flush_blocking(); } }) .build() }}build 方法是核心。它做了几件事：
1. 注册 command handler — invoke_handler告诉 Tauri 前端可以调用哪些命令2. setup 阶段初始化 — 创建 TelemetryClient，启动定时刷新，安装 panic hook3. 监听退出事件 — 在 RunEvent::Exit时强制 flush 所有待发事件4. 管理状态 — 通过 app.manage(client)把客户端放进 Tauri 的状态管理器
注意 plugin::Builder::new("telemetry") 里的 "telemetry" 就是插件的名字，前端调用时的命令格式是 plugin:telemetry|track_event。
这里有个坑：start_polling 必须用 tauri::async_runtime::spawn 而不是 tokio::spawn，因为 Tauri 的 setup 钩子不一定在 Tokio runtime 里运行。我一开始用的 tokio::spawn，在某些平台上会 panic。这种坑你不踩一次根本不知道。
核心架构：事件是怎么从"调用"到"发送"的
这是整个插件最关键的部分。我画了个流程：
下面逐个拆解。
TelemetryClient —— 事件的组装者
pub struct TelemetryClient { is_enabled: bool, session: SyncMutex<TrackingSession>, dispatcher: Arc<EventDispatcher>, app_version: String, sdk_name: String, sys_info: SystemProperties,}TelemetryClient 是插件的核心。它负责：
1. 判断是否启用（没有 host 就禁用） 2. 管理 session（4 小时超时，自动生成新 session ID） 3. 组装事件 JSON 4. 把事件扔给 dispatcher
每次调用 track_event，它会组装一个这样的 JSON：
{ "timestamp": "2026-06-26T10:30:00Z", "sessionId": "171939420000000012345678", "eventName": "click", "systemProps": { "isDebug":false, "osName": "macOS", "osVersion": "14.5", "locale": "zh-CN", "engineName": "WebKit", "engineVersion": "18.0", "appVersion": "1.0.0", "sdkVersion": "tauri-plugin-telemetry@0.1.2" }, "props": { "button": "save" }}注意 systemProps 里的信息是自动采集的，用户不需要手动传。这就是 Aptabase 的设计理念——最少侵入、最大信息量。
EventDispatcher —— 事件的搬运工
dispatcher.rs 是我花心思最多的部分。它要解决的问题是：不能每来一个事件就发一次 HTTP 请求，太浪费了。
pub(crate) struct EventDispatcher { url: Url, queue: Arc<RwLock<VecDeque<Value>>>, http_client: reqwest::Client,}设计思路：
• 队列缓冲：事件先进 VecDeque，不立刻发送• 批量发送：每次 flush 最多取 25 条，打包成一个 JSON 数组发送 • 失败重试：如果 HTTP 请求失败（服务端错误），把事件放回队列 • 超时控制：HTTP 请求 10 秒超时，不会卡住
pub async fn flush(&self) { if self.is_empty() { return; } let mut failed_items = Vec::new(); loop { let events_to_send = self.dequeue_many(25); if events_to_send.is_empty() { break; } let body = json!(events_to_send); let response = self.http_client .post(self.url.clone()) .json(&body) .send() .await; match response { Ok(resp) if resp.status().is_success() => { // 发送成功，不做任何事 } Ok(resp) if resp.status().is_server_error() => { // 服务端错误，事件放回队列 failed_items.extend(events_to_send); } Err(_) => { // 网络错误，事件放回队列 failed_items.extend(events_to_send); } _ => {} // 客户端错误（如 4xx），直接丢弃 } } // 把失败的事件重新入队 self.enqueue_many(failed_items);}有个设计决策值得说：4xx 错误（客户端错误）的事件直接丢弃，不重试。因为如果是 400 Bad Request，重试多少次都没用。只有 5xx（服务端错误）和网络错误才重试。这个策略参考了大多数 SDK 的做法。
Session 管理 —— 用时间戳 + 随机数生成 session ID
static SESSION_TIMEOUT: Duration = Duration::from_secs(4 * 60 * 60); // 4 小时fn new_session_id() -> String { let epoch_in_seconds = SystemTime::now() .duration_since(UNIX_EPOCH) .expect("time went backwards") .as_secs(); let mut rng = rand::rng(); let random: u64 = rng.random_range(0..=99999999); let id = epoch_in_seconds * 100_000_000 + random; id.to_string()}Session ID 的生成方式是 时间戳 * 1亿 + 随机数。这样做的好处是：
1. 可排序：按 session ID 排序就是按时间排序 2. 大概率唯一：随机数 8 位，同一秒内碰撞概率极低 3. 不依赖 UUID 库：减少依赖
Session 超时 4 小时——如果用户超过 4 小时没有操作，下次事件会生成新的 session ID。这个值是参考 Google Analytics 的 30 分钟超时，但我觉得桌面应用的用户行为模式跟 Web 不一样，可能长时间不操作但并没有关闭应用，所以设长一些。
系统信息采集 —— 跨平台的细节
pub fn get_info() -> SystemProperties { let info = os_info::get(); let locale = sys_locale::get_locale().unwrap_or_default(); let engine_version = webview_version().unwrap_or_default(); let os_name = match info.os_type() { os_info::Type::Macos => "macOS".to_string(), os_info::Type::Windows => "Windows".to_string(), #[cfg(target_os = "linux")] _ if is_flatpak() => "Flatpak".to_string(), _ => info.os_type().to_string(), }; SystemProperties { is_debug: IS_DEBUG, os_name, os_version: info.version().to_string(), locale, engine_name: ENGINE_NAME.to_string(), engine_version, }}注意几个细节：
• macOS 不写 "Macos"，手动改成 "macOS"——因为 os_info库返回的是枚举名，不是显示名• Linux 上检测了 Flatpak 环境——Flatpak 沙箱里的行为跟普通 Linux 不一样，值得单独标记 • WebView 引擎名称是 #[cfg]条件编译的——macOS/iOS 是 WebKit，Windows 是 WebView2，Linux 是 WebKitGTK，Android 是 Android System WebView
这些细节看起来不起眼，但做跨平台插件的时候，这些才是让你 debug 到头秃的地方。
前端绑定：TypeScript 怎么调用 Rust
webview-src/index.ts 简单到不能再简单：
import { invoke } from '@tauri-apps/api/core'type Props = { [key: string]: string | number;};export async function trackEvent(name: string, props?: Props): Promise<void> { await invoke<string>('plugin:telemetry|track_event', { name, props });}核心就一个 invoke 调用。plugin:telemetry|track_event 是 Tauri 的 IPC 命令格式——plugin:{插件名}|{命令名}。
注意 Props 类型只允许 string | number，不允许嵌套对象。这是故意的——扁平的 key-value 对后端最容易处理，也避免了用户传入过深的嵌套结构导致序列化问题。
用户在前端用起来就是这样：
import { trackEvent } from "tauri-plugin-telemetry";// 无属性事件trackEvent("app_started");// 有属性事件trackEvent("screen_view", { name: "Settings" });trackEvent("purchase", { plan: "pro", price: 9.99 });不需要 await——事件会进队列，后台自动发送。这是个有意的设计：前端不应该被遥测逻辑阻塞。
后端无关：怎么做到的
这是我的插件跟 Aptabase 原版最大的区别。Aptabase 的插件绑定了它自己的后端 URL，而我的插件通过 InitOptions 让用户自己指定：
#[derive(Default, Debug, Clone)]pub struct InitOptions { pub host: Option<String>, // 后端地址 pub flush_interval: Option<Duration>, // 刷新间隔 pub api_path: Option<String>, // API 路径，默认 /v1/events pub app_key_header: Option<String>, // App Key 的 HTTP header 名 pub sdk_name: Option<String>, // SDK 版本标识}host 是必须的——不设置 host 就不启用追踪。这个设计决策是刻意的：宁可不追踪，也不要偷偷把数据发到某个默认地址。隐私优先。
Config 的解析逻辑里有个细节：
let Some(base_url) = opts.host.clone() else { debug!("No backend host configured. Tracking will be disabled."); return Config::default();};如果没设置 host，直接返回默认 Config（app_key 为空），整个追踪系统就静默禁用了。TelemetryClient 里检查 is_enabled，如果禁用就直接返回，连队列都不进。
我个人觉得这种"显式启用"的设计比"默认开启"要好。尤其是遥测这种敏感功能，用户应该清楚地知道自己在追踪什么、发到哪里。
安全与权限：Tauri v2 的 ACL
Tauri v2 引入了 Access Control List（ACL）机制。每个插件命令默认是不可调用的，必须在 capabilities 文件里显式声明：
{ "permissions": ["telemetry:allow-track-event"]}这个权限是 build.rs 里声明的 COMMANDS 自动生成的。Tauri 的构建系统会创建 permissions/autogenerated/commands/track_event.toml：
[[permission]]identifier = "allow-track-event"description = "Enables the track_event command without any pre-configured scope."commands.allow = ["track_event"][[permission]]identifier = "deny-track-event"description = "Denies the track_event command without any pre-configured scope."commands.deny = ["track_event"]这是 Tauri v2 跟 Electron 最大的安全差异之一。Electron 的 renderer 进程默认可以调用所有 Node.js API（除非你手动限制），而 Tauri 的前端默认什么都不能做，必须逐个授权。
踩过的坑和设计决策
写这个插件的过程中，有几个点值得单独说：
1. 用 tauri::async_runtime::spawn 而不是 tokio::spawn
前面提过，Tauri 的 setup 钩子不一定在 Tokio runtime 里。如果你用 tokio::spawn，在某些情况下会 panic："there is no reactor running"。用 tauri::async_runtime::spawn 就没这个问题，Tauri 会帮你处理好 runtime 的选择。
2. flush_blocking 用 futures::executor::block_on
在 RunEvent::Exit 的时候，你已经不在 async 上下文里了，但你需要同步地 flush 事件。这里用了 futures::executor::block_on 而不是 tokio::runtime::Runtime::block_on，因为后者在已经有一个 Tokio runtime 的情况下会报错。
pub fn flush_blocking(&self) { futures::executor::block_on(async { self.flush().await; });}3. Panic Hook 保证事件不丢
如果应用 panic 了，队列里可能还有没发出去的事件。我加了个 panic hook 机制：
fn install_panic_hook(hook: PanicHook, client: Arc<TelemetryClient>) { let default_panic = std::panic::take_hook(); std::panic::set_hook(Box::new(move |info| { let msg = get_panic_message(info); hook(&client, info, msg); client.flush_blocking(); // panic 前强制 flush default_panic(info); // 然后执行默认的 panic 处理 }));}这样即使应用崩溃，至少最后一批事件能发出去。用户可以通过 with_panic_hook 自定义 panic 时的处理逻辑，比如把 panic 信息也作为事件发送。
4. Release 和 Debug 用不同的 flush 间隔
#[cfg(not(debug_assertions))]static DEFAULT_FLUSH_INTERVAL: Duration = Duration::from_secs(60);#[cfg(debug_assertions)]static DEFAULT_FLUSH_INTERVAL: Duration = Duration::from_secs(2);开发时 2 秒一刷，方便调试；生产环境 60 秒一刷，减少网络请求。这种小细节提升开发体验。
怎么在你的项目里用
如果你也想在 Tauri 项目里接入这个插件，步骤很简单：
第一步，在 src-tauri/Cargo.toml 里加依赖：
[dependencies]tauri-plugin-telemetry = "0.1.2"第二步，注册插件：
fn main() { tauri::Builder::default() .plugin( tauri_plugin_telemetry::Builder::new("YOUR_APP_KEY") .with_host("https://your-analytics-backend.com") .build() ) .run(tauri::generate_context!()) .expect("error while running tauri application");}第三步，在 capabilities 里加权限：
{ "permissions": ["telemetry:allow-track-event"]}第四步，前端发事件：
import { trackEvent } from "tauri-plugin-telemetry";trackEvent("app_started");trackEvent("feature_used", { feature: "export" });完事。后端你可以用 Aptabase 的托管服务，也可以自己搭——只要它能接收 POST /v1/events，body 是 JSON 数组就行。
结论
写这个插件的初衷很简单：Tauri 生态需要一个好用的、不绑定特定后端的遥测插件。Aptabase 的设计思路很好——隐私优先、最少侵入、自动采集系统信息——但它的实现绑死了自己的后端。我的目标是把这些好的设计提取出来，做成一个通用的、可扩展的插件。
整个插件的核心代码不到 500 行 Rust，加上 TypeScript 绑定也就 10 行。Tauri v2 的插件系统设计得确实不错——build.rs 声明命令、setup 钩子初始化、manage 管理状态、invoke_handler 处理 IPC，整个流程很清晰。
如果你也在做 Tauri 应用，需要统计功能，可以试试这个插件。如果你对插件开发有什么想法或者踩了什么坑，也欢迎来 GitHub 提 issue。
https://github.com/lispking/tauri-plugin-telemetry
写插件最难的不是代码，是那些跨平台的边界情况。哪个平台的 WebView 引擎叫什么名字、Flatpak 沙箱里怎么检测、panic 的时候怎么保证事件不丢——这些细节才是真正花时间的地方。但正是这些细节，决定了一个插件是"能用"还是"好用"。
