从零手搓一个 Tauri 插件：我魔改了 Aptabase 的设计，做了一个后端无关的遥测插件
起因：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 方法是核心。它做了几件事：
- 注册 command handler —
invoke_handler告诉 Tauri 前端可以调用哪些命令 - setup 阶段初始化 — 创建
TelemetryClient，启动定时刷新，安装 panic hook - 监听退出事件 — 在
RunEvent::Exit时强制 flush 所有待发事件 - 管理状态 — 通过
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。这种坑你不踩一次根本不知道。
核心架构：事件是怎么从"调用"到"发送"的
这是整个插件最关键的部分。我画了个流程：
前端 trackEvent("click", {button: "save"})
│
▼
commands.rs (IPC 命令处理)
│
▼
client.rs (TelemetryClient)
│ 组装事件 JSON（加上 sessionId、systemProps、timestamp）
▼
dispatcher.rs (EventDispatcher)
│ 入队到 VecDeque<Value>
│
│ 定时 flush（每 60s release / 2s debug）
│ 或者 exit 时强制 flush
▼
HTTP POST 到 {host}{api_path}
│
│ 批量发送，每批最多 25 条
│ 失败的事件重新入队
▼
后端接收
逐个拆解。
TelemetryClient —— 事件的组装者
pub struct TelemetryClient {
is_enabled: bool,
session: SyncMutex<TrackingSession>,
dispatcher: Arc<EventDispatcher>,
app_version: String,
sdk_name: String,
sys_info: SystemProperties,
}TelemetryClient 是插件的核心。它负责：
- 判断是否启用（没有 host 就禁用）
- 管理 session（4 小时超时，自动生成新 session ID）
- 组装事件 JSON
- 把事件扔给 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亿 + 随机数。这样做的好处是：
- 可排序：按 session ID 排序就是按时间排序
- 大概率唯一：随机数 8 位，同一秒内碰撞概率极低
- 不依赖 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。
写插件最难的不是代码，是那些跨平台的边界情况。哪个平台的 WebView 引擎叫什么名字、Flatpak 沙箱里怎么检测、panic 的时候怎么保证事件不丢——这些细节才是真正花时间的地方。但正是这些细节，决定了一个插件是"能用"还是"好用"。