Tauri 完整上手指南：3 步从零搭出可打包的桌面应用

Tauri 完整上手指南：3 步从零搭出可打包的桌面应用

【免费下载链接】tauriBuild smaller, faster, and more secure desktop and mobile applications with a web frontend.项目地址: https://gitcode.com/GitHub_Trending/ta/tauri

Tauri 是一个用 Rust + Web 技术栈构建桌面应用（也支持移动端）的框架：界面用你熟悉的 HTML/CSS/JS 写，系统能力交给 Rust，最终产出一个体积很小的原生安装包。这篇指南不讲概念堆砌，而是沿着「装好工具 → 生成项目 → 跑起来 → 打包」这条线，用最少必要的命令把一个能分发的 Tauri 应用完整走一遍，并附上新手最常卡住处的排查方法。

先弄清 Tauri 在跑什么：1 个 Rust 进程 + 1 个系统 WebView

理解 Tauri 只需要一张心智图：你的程序是一个 Rust 编译出的进程，界面则渲染在操作系统自带的 WebView 里——Windows 上是 WebView2，macOS 上是 WKWebView，Linux 上是 webkit2gtk。这正是它区别于其他 Electron 系方案的地方：不往应用里塞一份浏览器内核，所以安装包能压到很小，同时二进制是 Rust 编译产物，逆向成本也更高。

代价是 Linux 系统必须预先装好webkit2gtk-4.1这类开发库，后面装环境时脚本会帮你处理。代码层面，核心逻辑在crates/tauri/，运行时抽象在crates/tauri-runtime/，配置解析和平台工具在crates/tauri-utils/，想深入时可以看仓库根目录的ARCHITECTURE.md。

一条命令装齐 Rust 工具链和系统依赖

Tauri 官方提供了安装脚本，它会按你的操作系统自动装好 Rust 工具链和对应的 WebView 依赖，比手动逐个装省心：

# Windows（PowerShell） # iex "& { (New-Object Net.WebClient).DownloadString('https://install.tauri.app/install.ps1') }" # macOS / Linux curl --proto '=https' --tlsv1.2 -sSf https://install.tauri.app/sh | sh

跑完后用rustc --version和node -v各确认一次，两者都有输出就说明环境就绪。如果脚本中途失败，通常是网络问题，稍后「卡住了」一节有手动兜底方案。

30 秒用 create-tauri-app 生成可运行的项目

脚手架create-tauri-app会交互式地问你四个问题：项目名、前端框架（Vanilla / Vue / React / Svelte 等任选）、包管理器、是否立即装依赖。选完直接启动：

npm create tauri-app@latest my-app # yarn / pnpm 用户有对应写法 cd my-app npm run tauri dev

tauri dev会同时拉起前端开发服务器和 Rust 端，几秒后弹出一个原生窗口。之后你在前端改任何代码，窗口里的页面都会热更新，但 Rust 端的改动需要重新编译才会生效——这是开发期唯一需要记住的不对称行为。

10 秒定位你最需要知道的 3 个文件

项目结构其实就两半：前端代码（任何 Web 框架的组织方式都行）和src-tauri/目录（Rust 后端）。真正高频接触的文件只有三个：

• src-tauri/tauri.conf.json—— 唯一的核心配置：窗口尺寸标题、前端产物路径、安全策略、打包选项都在这。它是编译期读取的，改了要重新编译，编辑器会按crates/tauri-cli/tauri.config.schema.json给的 schema 做校验和补全，跟着提示写基本不会错。
• src-tauri/Cargo.toml—— Rust 依赖清单，加原生能力就在这里声明 crate。
• src-tauri/src/main.rs—— Rust 入口，应用在这里启动，自定义命令也在这里注册。

一份典型配置长这样，对照看一遍就知道每个字段管什么：

{ "productName": "my-app", "version": "0.1.0", "identifier": "com.example.myapp", "build": { "frontendDist": "../dist" }, "app": { "windows": [{ "title": "My App", "width": 800, "height": 600 }], "security": { "csp": "default-src 'self'" } } }

其中frontendDist指向前端构建产物目录，security.csp限制页面能加载哪些来源。想看真实项目怎么写，可以克隆仓库后翻examples/目录，里面有 helloworld、状态管理、流式通信等十几个小样例：

git clone https://gitcode.com/GitHub_Trending/ta/tauri

前端调用 Rust 后端的最短路径

Tauri 的 IPC 模型是「Rust 定义命令，前端调用命令」。Rust 侧只需要两步：给普通函数加上#[tauri::command]属性，再把它挂到 Builder 的.invoke_handler(tauri::generate_handler![greet])上。前端侧就是一行await invoke('greet', { name: 'Tauri' })，参数名要与 Rust 函数形参一一对应。

有两点值得留意：一是命令名在 Rust 端用下划线风格、前端会自动做驼峰转换；二是 Tauri 2.x 默认「权限拒绝优先」，自定义命令要在src-tauri/capabilities/的能力文件里声明后前端才能调用，忘了这一步会报无权限错误，看起来像调用写错了，实际是安全策略拦下的。

一条命令产出三大平台的安装包

开发完成后，构建发布版的命令是：

npm run tauri build

它会先编译 release 版 Rust 二进制，再由打包器按平台生成安装包，产物落在src-tauri/target/release/bundle/下：Windows 得到.msi和 NSIS 安装的.exe，macOS 得到.app与.dmg，Linux 得到.deb、.rpm和.AppImage📦。打包逻辑全部在crates/tauri-bundler/里，想改图标、自定义安装器行为，改的也是tauri.conf.json的bundle段。

卡住了先查这 3 处

新手 90% 的问题集中在这三个地方，按序排查基本都能解决：

1. 依赖装不上：多半是脚本没跑完或 Rust 工具链缺失。手动兜底：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh装 Rust；Linux 上再用包管理器补libwebkit2gtk-4.1-dev、libgtk-3-dev等开发库。
2. 窗口是白的 / 找不到页面：九成是前端产物对不上。确认前端已执行构建、tauri.conf.json里的frontendDist指向真实存在的目录；tauri dev场景下再检查 dev server 地址和端口是否被前端框架改过（比如 Vite 默认 5173，框架换了端口就要在配置里同步）。
3. invoke报命令不存在或无权限：先确认 Rust 端的命令真的注册进了invoke_handler；还报错的话去capabilities/里给该命令补权限声明。

走完这一遍，你手上已经有了环境、跑通的项目、可改的配置和一个可分发的安装包。下一步建议直接打开仓库里的examples/，挑一个离你需求最近的样例照着改，比继续读文档更快。

【免费下载链接】tauriBuild smaller, faster, and more secure desktop and mobile applications with a web frontend.项目地址: https://gitcode.com/GitHub_Trending/ta/tauri