Tauri 2 轻量桌面壳：同一套 Web 前端的 Rust 化实践

技术栈：Tauri 2.11 · Rust 1.77 · 系统 WebView · Python FastAPI · tauri-plugin-clipboard-manager / single-instance
关键词：桌面壳 · 进程管家 · 端口动态化 · capabilities 安全模型

一、技术背景：当"包体积"成为硬指标

Electron 版解决了业务问题，但有一个无法回避的代价：Chromium 整包。一个简单的桌面工具，发布体积动辄几百 MB，启动内存几百 MB，这在分发和运维上是实打实的成本。

Tauri 2 的解题思路完全不同：用操作系统自带的 WebView 渲染，用 Rust 做核心壳。没有 Chromium、没有 Node.js 运行时，打包产物是一个几十 MB 的原生二进制。更重要的是，Tauri 2 的插件机制（剪贴板、单实例、自动更新、托盘）正在快速补齐桌面能力，跨平台发布（含移动端）的路线图也相当清晰。

这个项目还有一个特殊架构，让 Tauri 化变得格外顺理成章：

前端页面不是 Tauri 打包进去的静态文件，而是由 Python 后端通过 HTTP 提供的。

窗口用 WebviewUrl::External("http://127.0.0.1:<port>") 直接加载后端地址。这意味着 Tauri 壳退化为纯粹的启动器 + 进程管家——业务逻辑全部在 Python 侧，Rust 只负责三件事：拉起后端、等它就绪、管好它的生死。

二、实现：一个 Rust 进程管家的自我修养

架构总览

┌─────────────────────────────────────────────┐
│  Tauri 壳（Rust · lib.rs）                    │
│  职责：端口探测 · 拉起后端 · 健康检查 ·        │
│        退出清理 · 单实例 · 剪贴板 IPC          │
└──────────────┬──────────────────────────────┘
               │ spawn（venv python / 冻结二进制）
┌──────────────▼──────────────────────────────┐
│  Python 后端（FastAPI · 端口动态分配）          │
└──────────────┬──────────────────────────────┘
               │ WebviewUrl::External 加载
┌──────────────▼──────────────────────────────┐
│  系统 WebView（渲染同一套 web/ 前端）           │
└─────────────────────────────────────────────┘

1. 端口动态化：一个常量，贯穿五个使用点

后端端口不再硬编码。Rust 侧用 pick_backend_port() 从 8787 起探测，被占用就向后顺延最多 20 个端口；这个端口通过一个 BackendPort state 贯穿窗口 URL、健康检查轮询、get_app_info 命令五个使用点。前端也因此收益：API 地址统一用 location.origin（WebView 加载的就是后端地址），端口顺延对前端完全透明。

2. 进程生命周期：两阶段清理，三条退路

Rust 侧维护 BackendProcess(Mutex<Option<Child>>)，清理逻辑 kill_backend() 幂等，挂了三个触发点：

RunEvent::Exit 兜底：App::run 回调里，进程真正退出时确保后端被终止；
SIGTERM / SIGINT 信号监听：外部 kill（系统关机、进程管理工具）也能走正常退出流程触发清理；
两阶段 kill：Unix 先 SIGTERM 等 1 秒让 uvicorn 落盘日志，超时再 SIGKILL；Windows 直接 terminate。

这里有个很容易踩的坑：macOS 上关闭窗口默认不退出应用（与 Electron 惯例一致），所以不能在窗口 Destroyed 事件里清理后端——否则用户关窗后再点 Dock 重开，后端已死、页面加载必然失败。正确做法是清理只挂在真正退出路径上，Windows/Linux 关窗会自然触发 ExitRequested → Exit，macOS 上由 Cmd+Q 触发。

3. IPC 打通：纯静态页面 + 全局注入

前端是后端 HTTP 提供的纯静态页，没有打包器，import('@tauri-apps/api/...') 这类动态导入在浏览器环境根本无法解析。打通方案是两件事：

tauri.conf.json 开启 withGlobalTauri: true（注意：它是 app 的顶层字段，不是 security 的子字段，放错位置编译直接报 unknown field），把 window.__TAURI__ 注入页面；
capabilities/default.json 配置 remote.urls 放行回环地址访问 IPC，并显式授予剪贴板权限：

{
  "remote": { "urls": ["http://127.0.0.1:*", "http://localhost:*"] },
  "permissions": [
    "core:default",
    "clipboard-manager:allow-read-text",
    "clipboard-manager:allow-write-text"
  ]
}

剪贴板用官方 tauri-plugin-clipboard-manager（命令为 plugin:clipboard-manager|read_text / write_text），前端 helper 三端统一：Electron preload → Tauri 插件 → 浏览器 navigator.clipboard 兜底。

4. 单实例锁与其它健壮性

tauri-plugin-single-instance 让第二次启动聚焦已有 main 窗口并退出新实例。还有一个容易忽视的细节：log::info! 在未初始化 logger 时是 no-op，诊断日志要复用项目自己的 log_main 落盘，否则排障时什么都看不到。

5. 打包与分发

cargo tauri build 一条命令产出各平台产物。macOS 上 DMG 生成依赖 create-dmg，在没有该工具的环境里退化为 hdiutil create -srcfolder。最终产物：.app 约 27 MB（12 MB 的 arm64 Rust 二进制 + 16 MB 冻结后端 + 前端资源），相比 Electron 版的几百 MB，体积优势一目了然。

三、踩过的坑（含金量最高的部分）

project_root() 多退一层目录——CARGO_MANIFEST_DIR 到项目根只需 2 次 parent()，写 3 次会落到上一层目录，导致 venv 找不到、回退到系统 python3、ModuleNotFoundError: api。这个 bug 潜伏很久从未暴露，因为 Tauri 版此前从未真正运行过 dev 模式。教训：路径派生逻辑一定要实测，不能只靠注释推断。
macOS 关窗杀后端——见上文，窗口 Destroyed 里杀进程是经典误伤。
withGlobalTauri 配置位置——放 security 里编译直接报 unknown field。
端口顺延后前端连错——web/log_viewer.js 残留过 __TAURI__ ? 'http://127.0.0.1:8787' : location.origin，withGlobalTauri 开启后 __TAURI__ 存在，反而走了错误的硬编码分支。教训：开启全局注入后，所有 __TAURI__ 条件分支都要重新审视。

四、应用与前景

Tauri 版与 Electron 版并列发布、功能等价：共用同一套 web/ 前端、同一个 api/server.py 后端、同一份 PyInstaller 冻结产物，双端行为已对齐到端口动态化、单实例、剪贴板、退出清理四个维度。用户按需选择——要稳妥选 Electron，要轻量选 Tauri。

Tauri 的前景判断：

体积与资源占用是长期优势，对分发渠道（下载带宽、安装体验）和低配机器尤其友好；
Rust 生态在快速成长，官方插件体系（updater / tray / notification / single-instance）持续补齐，移动端（iOS/Android）路线图已落地，是"一套代码多端"的潜在路径；
局限也真实：各平台系统 WebView 渲染差异需要兼容测试，Rust 上手门槛高于 JS，第三方插件成熟度参差。

对"Python 后端 + Web 前端"型项目来说，Tauri 提供了一种极优的打包方案：业务逻辑零改动，只换一个更轻的壳。这条路值得同类项目参考。

本文为 Jira Git GUI 项目技术博客系列（Tauri 篇），姊妹篇见《用 Electron 封装 Python 后端：Jira Git GUI 的桌面化实践》。

Zhaoqi.Cao static blog

A static personal blog.