Tauri + Rust 技术栈与编译说明

本文以 csv_editor_app 为例，说明基于 Tauri 2 + Rust + React + Vite + TypeScript 的桌面应用开发环境、编译流程与技术栈。

0. 参考项目

本文配套的示例项目 csv_editor_app 可以从以下地址下载：

• csv_editor_app-main.zip

下载后解压，即可按照下文步骤进行编译和运行。

1. Tauri + Rust 框架介绍

1.1 什么是 Tauri

Tauri 是一个使用 Web 前端技术构建跨平台桌面应用（以及移动端应用）的框架。它的核心思路是：

• 前端：使用 React / Vue / Svelte / 原生 JS 等 Web 技术开发界面。
• 后端/原生层：使用 Rust 编写，负责与操作系统交互（窗口、文件、对话框、通知等）。
• 运行时：操作系统自带的 WebView 渲染前端，Rust 进程提供原生能力，二者通过 Tauri 的 IPC 机制通信。

1.2 架构模式

┌─────────────────────────────────────────┐
│  前端 UI 层（React + TypeScript）          │
│  运行在系统 WebView 中                   │
└────────────┬────────────────────────────┘
             │ IPC（进程间通信）
┌────────────▼────────────────────────────┐
│  Rust 后端层（Tauri Runtime）             │
│  窗口管理、文件读写、系统对话框等         │
└─────────────────────────────────────────┘

1.3 Tauri + Rust 的主要优势

• 体积小：相比 Electron，Tauri 应用不需要打包 Chromium，安装包通常只有几 MB 到十几 MB。
• 启动快、内存占用低：运行时复用系统 WebView，没有冗余的浏览器内核。
• 安全性高：Rust 的内存安全特性 + Tauri 的权限系统（capabilities），默认最小权限原则。
• 原生性能：文件 IO、CPU 密集型计算等操作在 Rust 侧执行，性能接近原生应用。
• 跨平台：一份代码可构建 Windows、macOS、Linux 桌面应用；Tauri 2 还支持 iOS / Android 移动端构建。
• 复用 Web 生态：前端可以复用 npm 生态中的 UI 库、工具链、组件库等。

1.4 Tauri 与 Electron 的对比

2. 基础开发环境安装

本项目默认使用 bun 作为包管理器，请优先使用 bun 执行所有前端依赖安装与脚本命令。若不使用 bun，需自行将下述命令中的 bun 替换为对应的包管理器，并同步修改 src-tauri/tauri.conf.json 中的 beforeDevCommand 和 beforeBuildCommand。

2.1 Node.js / bun

Tauri 前端使用 npm 生态。项目脚本默认通过 bun 调用，因此需要先安装 bun。同时需要安装 Node.js（建议 LTS v22 或更高）以兼容前端工具链。

• 建议安装 LTS 版本（当前项目依赖 @types/node: ^24.12.0，建议 Node.js v22 或更高）。
• 使用 nodejs.org 官网安装包，或通过 nvm-windows 管理多版本。

安装后验证：

node -v   # 例如 v22.x.x
bun -v    # 例如 1.x.x

2.2 Rust 与 Cargo

Tauri 后端使用 Rust，通过 rustup 安装最新稳定版。

Windows 安装步骤：

1. 访问 https://rustup.rs/
2. 下载 rustup-init.exe 并运行。
3. 按提示选择默认安装（选项 1 - Proceed with default install）。
4. 安装完成后可能需要重新打开终端，或按提示执行环境变量刷新命令。

安装后验证：

rustc --version   # 例如 rustc 1.x.x
cargo --version   # 例如 cargo 1.x.x

2.3 Windows 下的 Tauri 系统依赖

Windows 平台编译 Tauri 需要以下额外工具：

（1）Microsoft Visual C++ Build Tools

Tauri 2 在 Windows 上编译 Rust 代码需要 MSVC 编译器。推荐安装 Visual Studio Build Tools 的 使用 C++ 的桌面开发 工作负载。

通过 winget 安装示例：

winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

或者从 Visual Studio 下载页面 手动下载 Build Tools 并勾选 使用 C++ 的桌面开发。

（2）WebView2 Runtime

• Windows 10/11 通常已内置 WebView2 运行时。
• 开发构建需要 WebView2 SDK，Tauri 工具链通常会自动处理。
• 如出现异常，可手动安装 WebView2 Runtime。

环境验证

完成上述安装后，在 PowerShell 或 Git Bash 中执行：

rustc --version
cargo --version
node -v
bun -v

全部正常输出版本号即表示 Windows 开发环境准备就绪。

3. 项目快速编译

3.1 进入项目目录并安装依赖

cd apps/csv_editor_app
bun install

执行后：

• 前端依赖下载到 node_modules/。
• src-tauri/Cargo.toml 中的 Rust 依赖会通过 Cargo 自动下载。

3.2 开发模式编译运行

bun run tauri dev

执行后：

• Vite 启动前端开发服务器，固定端口 1424（见 vite.config.ts）。
• Cargo 编译 Rust 后端，生成调试版本可执行文件。
• 自动打开应用窗口，标题为 CSV Editor，默认尺寸 1200x800。

首次编译 Rust 会下载并编译大量依赖，耗时较长，后续会利用增量编译加速。

3.3 生产模式编译打包

bun run tauri build

执行后：

• 前端执行 tsc -b && vite build，输出到 dist/。
• Rust 以 release 模式编译。
• 默认不打包安装程序（tauri.conf.json 中 bundle.active 为 false）。

本项目 tauri.conf.json 当前打包配置如下：

{
  "bundle": {
    "active": false
  }
}

如需生成安装包，可将其改为 true 并配置 targets（如 nsis）。注意首次打包安装程序可能需要从网络下载 NSIS 工具。

产物默认位于：

csv_editor_app/src-tauri/target/release/

直接可执行文件为：

src-tauri/target/release/csv-editor-app.exe

3.4 常用脚本速查

bun run dev          # 仅启动 Vite 前端开发服务器（不启动 Tauri 窗口）
bun run build        # 仅构建前端静态资源到 dist/
bun run preview      # 预览生产构建后的前端
bun run tauri dev    # 启动 Tauri 开发模式（Vite + Rust + 窗口）
bun run tauri build  # 完整构建 Tauri 桌面应用安装包
bun run test         # 运行 Vitest 单元测试
bun run test:run     # 单次运行 Vitest 测试
bun run lint         # 运行 ESLint 检查
bun run format       # 使用 Prettier 格式化代码
bun run typecheck    # 运行 TypeScript 类型检查

4. csv_editor_app 功能与技术栈

4.1 项目功能

csv_editor_app 是一个基于 Tauri 2 的桌面端 CSV 查看与编辑工具，核心功能包括：

• 通过系统对话框打开本地 CSV 文件。
• 以表格形式展示 CSV 内容并支持编辑。
• 将修改后的内容保存为 CSV 文件。
• 提供简洁的工具栏与状态管理。

4.2 主要技术栈

4.3 进一步探索

以下文件值得自行阅读：

• package.json：Node 依赖与脚本。
• vite.config.ts：Vite 开发服务器与路径别名配置。
• src-tauri/Cargo.toml：Rust 依赖与 release 优化配置。
• src-tauri/tauri.conf.json：应用名称、窗口、打包目标等核心配置。
• src-tauri/capabilities/default.json：前端可调用的原生能力权限声明。
• src-tauri/src/lib.rs：Rust 入口，插件初始化与窗口事件处理。
• src/components/CsvTable.tsx：CSV 表格组件。
• src/lib/csv.ts：CSV 解析逻辑。
• src/store/csvStore.ts：Zustand 状态管理。

5. 项目目录结构

csv_editor_app/
├── src/                          # 前端源代码
│   ├── App.tsx                   # 应用根组件
│   ├── components/
│   │   ├── CsvTable.tsx          # CSV 表格展示/编辑组件
│   │   ├── Toolbar.tsx           # 工具栏组件
│   │   └── ui/                   # shadcn/ui 组件库
│   ├── lib/
│   │   ├── csv.ts                # CSV 解析逻辑
│   │   ├── csv.test.ts           # CSV 解析单元测试
│   │   └── file.ts               # 文件操作辅助函数
│   ├── store/
│   │   └── csvStore.ts           # Zustand 状态管理
│   └── main.tsx                  # 前端入口
├── src-tauri/                    # Rust 后端与 Tauri 配置
│   ├── src/
│   │   └── lib.rs                # Rust 入口与插件初始化
│   ├── Cargo.toml                # Rust 依赖与构建配置
│   ├── tauri.conf.json           # Tauri 应用配置
│   ├── capabilities/
│   │   └── default.json          # 前端可调用原生 API 的权限声明
│   └── icons/                    # 应用图标
├── public/                       # 静态资源
├── dist/                         # 前端生产构建输出
├── docs/                         # 项目文档
├── package.json                  # Node 依赖与脚本
├── vite.config.ts                # Vite 配置
└── tsconfig*.json                # TypeScript 配置

6. 常见问题

6.1 Rust 编译缓慢

• 首次编译会下载并编译大量依赖，建议使用 SSD 并保持网络畅通。
• 后续开发中，cargo 会利用增量编译显著提速。
• 本项目 Cargo.toml 已开启 profile.dev.incremental = true，提升开发编译速度。

6.2 Windows 上提示缺少 MSVC

安装 Visual Studio Build Tools 的 使用 C++ 的桌面开发 工作负载。

6.3 bun 命令找不到

tauri.conf.json 当前写的是 bun run dev / bun run build。如果本机没有安装 bun，只有 npm，请将这两项改为：

"beforeDevCommand": "npm run dev",
"beforeBuildCommand": "npm run build"

6.4 前端调用 Rust 函数失败

检查 src-tauri/capabilities/default.json 中的权限配置，确保相关能力（如 fs:read、dialog:open 等）已声明并分配给对应窗口。

6.5 打包时报 NSIS 缺失 / 无法生成安装包

现象：bun run tauri build 在 Windows 上提示 NSIS 缺失或下载失败（%TEMP% 里可能残留一个下载了却没解压的 nsis-3.x.zip）。原因是本机连不上 GitHub，Tauri 的自动下载中断。

注意 Tauri 在 Windows 上不用系统已安装的 NSIS、也不读 NSIS_PATH 环境变量，只认自己的缓存目录 %LOCALAPPDATA%\tauri\NSIS\，所以"装一个 NSIS 然后设环境变量"是无效的。完整的离线修复步骤（基于公司 OSS，已验证可用）见下文「NSIS 工具链（Windows 打包依赖）」一节；该缓存全局共享，配好后本机所有 Tauri 项目均可直接打包。

6.6 NSIS 工具链（Windows 打包依赖）

Tauri 在 Windows 上生成 .exe 安装程序依赖 NSIS。它的获取机制与直觉不同，理解机制才能在自动下载失败时正确处理。

工作机制（关键，决定了解决思路）：

• Tauri 不使用系统已安装的 NSIS，也不读 NSIS_PATH 环境变量（该变量仅 macOS / Linux 生效）。Windows 下它只认自己缓存目录里的 NSIS：%LOCALAPPDATA%\tauri\NSIS\。
• 首次打包时，Tauri 会从 GitHub 自动下载两份文件到该缓存：
  1. NSIS 本体（nsis-3.x.zip，来自 tauri-apps/binary-releases）；
  2. Tauri 专属插件 nsis_tauri_utils.dll（来自 tauri-apps/nsis-tauri-utils，当前 v0.5.3）。
• 每次打包前，Tauri 会校验缓存中 13 个必需文件（NSIS_REQUIRED_FILES）是否齐全——缺任意一个就会整体删除并重新下载。其中只有 nsis_tauri_utils.dll 会被哈希校验（SHA1 75197fee3c6a814fe035788d1c34ead39349b860），NSIS 本体文件只检查是否存在。

常见故障现象（国内网络环境）：

打包时报 NSIS 缺失 / 下载失败，且 %TEMP% 下残留一个下载了却没解压的 nsis-3.x.zip。根因是本机无法稳定访问 GitHub（自动下载源头），导致下载或解压中断；杀毒软件误删缓存目录也会引发同样现象。

离线安装（推荐，已验证可用）：

公司已将所需文件发布到内网可达的 OSS，可完全不依赖 GitHub 完成配置。在 Git Bash 中执行：

CACHE="$LOCALAPPDATA/tauri"

# 1) 安装 NSIS 3.12（运行安装包，默认装到 C:\Program Files (x86)\NSIS）
#    下载：https://ppm-sources.oss-cn-hongkong.aliyuncs.com/zj/3rd/nsis-3.12-setup.exe

# 2) 把安装好的 NSIS 整体复制进 Tauri 缓存目录，命名为 NSIS
mkdir -p "$CACHE"
rm -rf "$CACHE/NSIS"
cp -r "/c/Program Files (x86)/NSIS" "$CACHE/NSIS"

# 3) 下载 Tauri 专属插件到指定位置
mkdir -p "$CACHE/NSIS/Plugins/x86-unicode/additional"
curl -L "https://ppm-sources.oss-cn-hongkong.aliyuncs.com/zj/3rd/nsis_tauri_utils.dll" \
  -o "$CACHE/NSIS/Plugins/x86-unicode/additional/nsis_tauri_utils.dll"

# 4) 校验插件完整性（应输出 75197fee3c6a814fe035788d1c34ead39349b860）
sha1sum "$CACHE/NSIS/Plugins/x86-unicode/additional/nsis_tauri_utils.dll"

完成后回到项目执行 bun run tauri build，Tauri 会跳过下载直接打包。

注意事项：

• 版本差异不影响打包：OSS 提供的是 NSIS 3.12，而 Tauri 默认下载 3.11。由于 Tauri 每次只校验插件 dll 的哈希、本体文件只查存在性，用 3.12 本体 + 正确插件即可正常打包（已在 @tauri-apps/cli 2.11.x 实测通过）。
• 缓存全局共享：配好一次后，本机所有 Tauri 项目共用 %LOCALAPPDATA%\tauri\NSIS\，无需对每个项目重复操作——新项目遇到同样问题，先检查该目录是否完整即可。
• 持久性：只要该缓存目录不被清理即可长期使用。建议在杀毒软件中把 %LOCALAPPDATA%\tauri\ 加入白名单，避免 makensis.exe 被误删后再次触发 GitHub 下载。
• Tauri 升级后插件版本漂移怎么办：OSS 上的 nsis_tauri_utils.dll 是 v0.5.3，与当前 @tauri-apps/cli 2.x 匹配。若升级 Tauri 后构建报插件哈希不匹配（日志出现 mis-hashed files / Redownloading），说明 OSS 版本已过时——直接自行下载即可，无需更新本文档的 SHA1：构建日志里会给出新的下载地址（形如 nsis_tauri_utils-vX.Y.Z），用浏览器从 GitHub 取回该 dll，替换缓存目录下 NSIS\Plugins\x86-unicode\additional\nsis_tauri_utils.dll 即可。NSIS 本体不受影响，无需重装。

相关下载地址汇总：

7. 其他：Linux 系统依赖（简要说明）

Linux 平台主要需要 GTK 和 WebKitGTK 开发库。以 Ubuntu/Debian 为例：

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo3 \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

macOS 环境需要安装 Xcode Command Line Tools：

xcode-select --install

8. 参考资源

• Tauri 官方文档
• Tauri 前置条件
• Rust 官方文档
• Vite 官方文档
• React 官方文档