Tauri Windows 桌面端：环境与构建流程

本文说明在本仓库（Vue 3 + Vite + Tauri 2）中，从环境准备到开发调试、再到发布打包的完整流程。

1. 概述

阶段	说明
仅前端	`npm run dev`：浏览器访问 Vite 开发服务（默认 `http://localhost:5176`），不涉及桌面壳。
桌面开发	`npm run tauri:dev`：启动 Vite + 打开 Tauri 窗口加载同一开发地址，用于联调桌面行为。
发布打包	`npm run tauri:build`：构建前端产物 + 编译 Rust Release，生成 Windows 安装包/可执行文件。

重要： tauri:dev 成功只表示开发环境可用 ，不等于发布包已生成 ；发布必须执行 tauri:build 并在输出目录取安装包。

2. 前置环境（Windows）

2.1 Node.js

本仓库 package.json 要求：Node ^20.19.0 或 >=22.12.0（建议使用 LTS，与团队一致）。
安装后执行：node -v、npm -v。

2.2 Rust 工具链（必需）

Tauri 依赖 Cargo ，需安装官方工具 rustup：

打开：https://rustup.rs/
下载 Windows 安装程序 rustup-init.exe （后缀名为 .exe），按向导安装，默认 stable 即可。
关闭并重新打开终端，执行：
bash 复制代码
```
rustc --version
cargo --version
```

若提示找不到命令，将 %USERPROFILE%\.cargo\bin 加入系统 Path 后再试。

2.3 MSVC 与 Windows SDK（Windows 上编译 Tauri 通常需要）

安装 Visual Studio Build Tools ，勾选 「使用 C++ 的桌面开发」（含 MSVC、Windows SDK）。
若本机已安装带「使用 C++ 的桌面开发」工作负载的 Visual Studio，一般可不再单独装 Build Tools。

2.4 WebView2

Windows 10/11 通常已自带或通过系统更新提供 WebView2 运行时；企业离线环境若缺失，需单独安装运行时（见微软文档）。

3. 仓库内与本流程相关的配置

3.1 前端开发端口与 Tauri 对齐

package.json 中："dev": "vite --host 0.0.0.0 --port 5176"
src-tauri/tauri.conf.json 中：devUrl 为 http://localhost:5176

修改端口时需两处同时改 ，否则 tauri dev 会连错地址。

3.2 构建产物目录

tauri.conf.json 中：frontendDist 为 ../dist，即 Vite 构建输出目录。
beforeBuildCommand 为 npm run build，会先执行项目自带的 build（含类型检查 + vite build），再打包 Tauri。

3.3 路由（Vue Router）

使用 createWebHistory（History 模式），与 Tauri 内置的 SPA 静态资源处理兼容；开发由 Vite 提供回退，生产由 Tauri 侧处理未匹配路径。

4. 首次克隆仓库后的步骤

在项目根目录执行：

bash 复制代码

npm install

确保已满足第 2 节中的 Rust / MSVC 等条件。

5. 日常开发（桌面预览）

bash 复制代码

npm run tauri:dev

等价于调用 @tauri-apps/cli 的 tauri dev：会先按配置启动 npm run dev（Vite），再拉起桌面窗口。

说明： 若只想在浏览器里调 UI，可使用：

bash 复制代码

npm run dev

6. 发布打包（生成安装包）

bash 复制代码

npm run tauri:build

该命令会：

执行 beforeBuildCommand：npm run build（生成 dist/）。
编译 Rust 为 Release ，并按 tauri.conf.json 的 bundle 配置打 Windows 包。

产物位置（常见）：

可执行文件与中间产物多在：src-tauri/target/release/
安装包、安装器等多在：src-tauri/target/release/bundle/ 下按平台分子目录（以本机实际生成为准）。

首次完整 Release 编译可能较慢，属正常现象。

7. 命令对照表

命令	用途
`npm run dev`	仅前端 Vite，端口 5176。
`npm run tauri:dev`	桌面开发模式（Vite + Tauri 窗口）。
`npm run build`	前端生产构建（含 `vue-tsc` 类型检查）→ 输出 `dist/`。
`npm run tauri:build`	正式发布打包（前端 build + Tauri 打安装包）。
`npm run tauri`	直接调用 CLI，可接子命令，如 `npm run tauri -- info`。

8. 常见问题

8.1 `cargo metadata` / `program not found`

原因： 未安装 Rust，或 cargo 不在 PATH。
处理： 按第 2.2 节安装 rustup，并确认新终端中 cargo --version 可用。

8.2 链接错误 / 缺少 MSVC

原因： 未安装 C++ 构建工具或未选 MSVC 相关组件。
处理： 按第 2.3 节安装或补全 Visual Studio Build Tools（含 MSVC）。

8.3 `tauri:dev` 白屏或连不上前端

检查 5176 端口是否被占用；是否与 devUrl 一致。
防火墙是否拦截本地回环（少见）。

8.4 应用标识与名称

当前 identifier 为示例值 com.tauri.dev，正式发布前建议在 src-tauri/tauri.conf.json 中改为贵司反向域名风格唯一 ID，并同步修改 productName、图标等 bundle 相关配置。

9. 参考链接

Rust 安装：https://rustup.rs/
Tauri 2 文档：https://v2.tauri.app/
Vite 与 Tauri：https://v2.tauri.app/start/frontend/vite/

文档与仓库脚本、配置保持一致；若你修改了端口、脚本名或 Tauri 版本，请同步更新本文对应小节。

Tauri Windows 桌面端：环境与构建流程