Tauri + Tailwind CSS 桌面端应用开发全流程入门教程
|
运维 / Linux / 服务器

本教程专门为零基础、或刚接触桌面端开发的同学编写。通过本篇教程，你将能够从零开始搭建环境、理解底层架构、运行并打包出一个高性能、超小体积的桌面端应用程序。

一、 技术栈简介

在本项目中，我们组合使用了目前全栈开发中最主流、最高效的几项技术：

  1. Tauri (桌面端核心框架)
    • 作用：负责把网页端程序“变成”桌面端软件。
    • 特点：它是 Electron 的下一代颠覆者。Electron 会在安装包里塞进一个完整的谷歌浏览器（导致软件体积动辄几百 MB，吃内存），而 Tauri 不自带浏览器。它直接调用你电脑系统自带的浏览器内核（Windows 内部调用 Edge WebView2，Mac 调用 Safari WebKit），因此打包出来的软件通常只有十几 MB，运行极快。
  2. Rust (后端编译与底层控制)
    • 作用：作为软件的后端。
    • 特点：普通的网页 JS 代码由于安全沙箱限制，是无法直接读取用户 C 盘文件、调用底层硬件或注册全局快捷键的。Rust 拥有极高的操作系统权限，它充当“幕后执法人”，前端需要读写文件或进行高级操作时，通过通信发送给 Rust，由 Rust 来安全、高效地完成。
  3. Vite + Vue 3 / React (前端工程化框架)
    • 作用：负责构建你的前端页面。Vite 是目前速度最快的前端构建工具，负责将你的网页代码压缩、打包。
  4. Tailwind CSS (原子化样式框架)
    • 作用：负责界面的极致美化。
    • 特点：无需再写单独的 .css 文件。你只需要在 HTML 的 class 属性里写简写类名（例如 class="flex p-4 bg-blue-500 rounded-lg"），就能瞬间拼装出精美的“苹果风”或“极简风”现代 UI 界面。

二、 核心架构与技术关系

在 Tauri 项目中，应用被划分为两个核心主进程，它们分工明确：

  1. 前端（渲染进程 - Webview）：由 HTML/JS/CSS（基于 Vite + Tailwind）构成。你在屏幕上看到的按钮、文字、动画都在这里渲染。它运行在系统自带的 WebView 内核中。
  2. 后端（主进程 - Rust Core）：由 Rust 编写。负责和操作系统直接打交道（如文件存储、系统托盘、网络请求、通知等）。
  3. 通信桥梁（IPC - 进程间通信）：前端和后端通过 Tauri 提供的命令机制（invoke）进行异步通信。前端发送指令，Rust 执行完后将结果返回给前端。

三、 开发环境安装（一次性配置）

在一切开始之前，你的电脑需要具备运行和编译前端及 Rust 后端的能力。

1. 前端环境：安装 Node.js

  • 下载：前往 Node.js 官网 下载长期支持版（LTS）。

  • 验证：打开终端（CMD 或 PowerShell），输入以下命令，看到版本号即代表成功：

    Bash

    node -v
npm -v

2. 后端环境：安装 Rust 及 C++ 编译工具（Windows 系统）

Rust 编译出 Windows 的 .exe 程序需要依赖微软的 C++ 编译环境。

  1. 下载并安装 Visual Studio 构建工具：

    • 前往 微软官网 下载 Visual Studio Build Tools。
    • 运行安装程序，在弹出的工作负载勾选界面，必须勾选“使用 C++ 的桌面开发”，然后点击安装并重启电脑。

  2. 安装 Rust 语言环境：

    • 前往 Rust 官网 下载 rustup-init.exe 并运行。
    • 终端弹出选项时，输入 1（选择默认的 default 安装）并回车。

  3. 验证 Rust 环境：

    • 重新打开终端，输入以下命令验证：

      Bash

      rustc --version
cargo --version

3. 国内网络加速配置（★ 极其重要）

由于 Rust 官方服务器在国外，国内网络直接下载依赖包极易卡死或报错（例如报 failed to get serde 等错误）。在开发前必须配置国内稀疏索引镜像。

  1. 按下快捷键 Win + R，输入 %USERPROFILE%\.cargo 并回车。

  2. 在打开的目录下，新建一个文本文档，将其重命名为 config.toml。 (⚠️ 注意：确保它的后缀是 .toml，而不是 config.toml.txt)

  3. 用记事本打开它，将以下内容复制进去并保存（注意末尾的斜杠不可省略）：

    Ini, TOML

    [source.crates-io]
replace-with = 'ustc'

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"

[net]
git-fetch-with-cli = true

四、 项目初始化与搭建

1. 创建 Tauri 项目

在你想存放项目的文件夹下打开终端，运行以下命令：

Bash

npm create tauri-app@latest

按照提示进行选择（推荐选择）：

  • Project name: 输入你的项目名（如 local-toolbox）
  • Identifier: 输入应用标识符（⚠️注意：不要以 .app 结尾，例如输入 com.toolbox.dev）
  • Choose which language to use for your frontend: 选择 TypeScript / JavaScript
  • Choose your package manager: 选择 npm
  • Choose your UI framework: 选择 Vue 或 React
  • Choose your Vite template: 选择对应的 Vue 或 React 模板

2. 初始化 Tailwind CSS

进入刚刚创建好的项目根目录：

Bash

cd local-toolbox

安装 Tailwind CSS 及其依赖项：

Bash

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

修改根目录下的 tailwind.config.js 文件，配置要应用样式的文件路径：

JavaScript

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx,vue}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

在你的前端主样式文件（例如 src/style.css 或 src/assets/main.css）的最顶部，引入 Tailwind 的三层核心指令，将其原有内容清空并替换为：

CSS

@tailwind base;
@tailwind components;
@tailwind utilities;

五、 项目目录结构介绍

一个标准的 Tauri 项目目录结构如下，开发时你只需要关注 src 和 src-tauri：

Plaintext

local-toolbox/
├── src/                      <-- 【前端核心】
│   ├── assets/               <-- 前端静态资源（图片、样式等）
│   ├── components/           <-- 前端 UI 组件
│   ├── App.vue / App.tsx     <-- 网页根组件（在此处编写你的工具界面）
│   └── main.js / main.ts     <-- 前端入口文件
├── src-tauri/                <-- 【后端核心（Rust）】
│   ├── icons/                <-- 软件桌面图标（打包时必用）
│   ├── src/
│   │   └── main.rs           <-- Rust 入口文件（编写底层逻辑、窗口控制的地方）
│   ├── Cargo.toml            <-- Rust 的依赖管理配置文件
│   └── tauri.conf.json       <-- 【全局配置】配置软件名、窗口大小、打包参数等
├── dist/                     <-- 【临时产物】前端网页编译后的静态文件夹
├── package.json              <-- 前端依赖管理配置文件
└── index.html                <-- 网页主入口

六、 常用开发与构建命令

在项目根目录下打开终端，通过以下命令来操纵你的项目：

1. 安装前端依赖

在新拉取项目或更换电脑后执行：

Bash

npm install

2. 启动开发模式（实时预览）

Bash

npm run tauri dev
  • 效果：系统会编译 Rust 并启动一个独立的桌面窗口。
  • 特性：支持热更新。你在前端代码（src/ 内部）修改任何界面或 Tailwind 样式，保存后桌面窗口里的界面会实时刷新，无需重新编译。

3. 生成正式打包文件

Bash

npm run tauri build
  • 效果：
    1. 自动执行前端打包，在 dist/ 生成静态网页。
    2. 启动 Rust 生产环境编译，把网页无缝内嵌到二进制文件中。
    3. 最终在 src-tauri/target/release/ 下生成绿色版 .exe。
    4. 调用打包工具生成安装包。

七、 常见避坑指南（新手必看）

1. 警告：Bundle identifier ends with .app

  • 原因：在 tauri.conf.json 中配置的 identifier 类似于 com.toolbox.app。因为 .app 在 macOS 系统中是合法的软件后缀名，冲突会导致 Mac 环境打包失败。
  • 解决：打开 src-tauri/tauri.conf.json，将 "identifier": "com.toolbox.app" 修改为 "identifier": "com.toolbox.dev" 即可。

2. 卡死在 Blocking waiting for file lock on package cache

  • 原因：之前的编译进程异常锁死，或者有多个终端同时在跑编译，导致 Rust 的缓存文件被锁住。
  • 解决：打开任务管理器，杀掉所有带有 cargo.exe 或 rustc.exe 的进程。或者前往 C:\Users\你的用户名\.cargo\ 目录下，删除名为 .package-cache 的锁文件。

3. 打包卡死在 Downloading https://github.com/wixtoolset/...

  • 原因：Tauri 在最后一步默认尝试将软件打包成 .msi 安装包，这需要下载微软的 WiX 工具链，由于 GitHub 在国内访问极其不稳定而导致卡死。
  • 终极解决方案（改用更轻量现代的 NSIS 打包，生成 exe 安装包）：
    1. 打开 src-tauri/tauri.conf.json。
    2. 找到 "bundle" 下的 "targets": "all"。
    3. 将其修改为："targets": ["nsis"]。
    4. 重新运行 npm run tauri build。NSIS 依赖下载极快，会自动为你生成精美的 项目名_x64-setup.exe 一键安装包。

八、 软件使用后，本地数据和配置文件存在哪里？

如果你在前端使用了最常用的网页存储方式（如 localStorage 或 IndexedDB）来存储用户的卡片、文本、配置数据，当用户安装并运行你的桌面端软件后，这些数据并不会随软件关闭而消失。

它们被安全地托管在 Windows 系统的 Edge WebView2 独立用户数据文件夹（UDF）中。具体存放路径如下：

  1. 按下快捷键 Win + R，输入 %LOCALAPPDATA% 并回车。

  2. 找到你在项目里设置的软件标识符文件夹（例如 com.toolbox.dev 或者是你的项目名称）。

  3. 数据的确切物理位置位于：

    Plaintext

    %LOCALAPPDATA%\[你的应用标识符]\EBWebView\Default\Local Storage\leveldb\

    即使你后续为软件覆盖安装升级版本，只要这个目录不被手动清空，用户的本地配置数据就绝不会丢失！

Tauri
上一篇
下一篇