【Tauri框架学习】Windows 11 环境下 Tauri 开发环境安装与问题解决手册

Windows 11 环境下 Tauri 开发环境安装与问题解决手册

- [Windows 11 环境下 Tauri 开发环境安装与问题解决手册](#Windows 11 环境下 Tauri 开发环境安装与问题解决手册)
- - [**一、Tauri 开发环境安装流程（Windows 11）**](#一、Tauri 开发环境安装流程（Windows 11）)
  - - [**1. 安装 Rust 工具链**](#1. 安装 Rust 工具链)
    - [**2. 安装 Microsoft C++ 构建工具**](#2. 安装 Microsoft C++ 构建工具)
    - [**3. 验证 WebView2 运行时**](#3. 验证 WebView2 运行时)
    - [**4. 安装 Node.js（前端项目需要）**](#4. 安装 Node.js（前端项目需要）)
    - [**5. 创建并运行 Tauri 项目**](#5. 创建并运行 Tauri 项目)
  - **二、常见问题与解决方法**
  - - [**1. Rust 安装超时**](#1. Rust 安装超时)
    - [**2. 编译时提示"缺少 C++ 构建工具"**](#2. 编译时提示“缺少 C++ 构建工具”)
    - [**3. 运行时提示"缺少 WebView2"**](#3. 运行时提示“缺少 WebView2”)
    - [**4. 应用启动后无窗口显示**](#4. 应用启动后无窗口显示)
    - [**5. 无装饰窗口无法调整大小**](#5. 无装饰窗口无法调整大小)
    - [**6. 拖动窗口卡顿（Acrylic 特效）**](#6. 拖动窗口卡顿（Acrylic 特效）)
  - **三、总结**

Windows 11 环境下 Tauri 开发环境安装与问题解决手册

一、Tauri 开发环境安装流程（Windows 11）

Tauri 是基于 Rust 的跨平台桌面应用框架，依赖 Rust 工具链 、C++ 构建工具 、WebView2 运行时 和 Node.js（前端项目需要）。以下是详细安装步骤：

1. 安装 Rust 工具链

Rust 是 Tauri 的后端核心语言，需通过 rustup 安装：

步骤：
1. 访问 Rust 官网（https://www.rust-lang.org/tools/install），下载 rustup-init.exe（64 位系统选择 x86_64-pc-windows-msvc）。
2. 运行 rustup-init.exe，选择 默认安装（或自定义安装路径），等待安装完成。
3. 安装完成后，重启终端（或运行 source $HOME/.cargo/env），验证安装：
  bash 复制代码
```
rustc --version  # 输出 Rust 版本（如 1.77.0）
cargo --version  # 输出 Cargo 版本（如 1.77.0）
```
注意：
- 若安装超时，可设置国内镜像（如 RUSTUP_DIST_SERVER=https://rsproxy.cn），再重新运行安装程序。
- 确保选择 MSVC 工具链 （x86_64-pc-windows-msvc），否则可能导致编译失败。

2. 安装 Microsoft C++ 构建工具

Tauri 编译需依赖 C++ 构建工具，需安装 Visual Studio Build Tools：

步骤：
1. 访问微软官网（https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/），下载 Visual Studio Build Tools 安装程序。
2. 运行安装程序，勾选 "使用 C++ 的桌面开发"（默认包含 MSVC 编译器、Windows SDK 等），点击"安装"。
3. 安装完成后，验证是否生效：
  bash 复制代码
```
cl.exe  # 输出 MSVC 编译器版本（如 19.37.32825）
```
注意：
- 若已安装 Visual Studio 2022，可直接通过"修改"功能添加"C++ 桌面开发"组件。

3. 验证 WebView2 运行时

Tauri 在 Windows 上使用 WebView2（Edge 浏览器的内核）渲染界面，Windows 11 通常已预装，但需验证：

步骤：
1. 打开 PowerShell，运行以下命令：
  powershell 复制代码
```
Get-AppxPackage Microsoft.WebView2
```
2. 若输出中包含 Microsoft.WebView2 包，则说明已安装；否则需手动下载安装：
  - 访问 WebView2 官网（https://developer.microsoft.com/zh-cn/microsoft-edge/webview2/），下载 Evergreen Bootstrapper（常青版引导程序），运行后自动安装。

4. 安装 Node.js（前端项目需要）

若需开发前端界面（如 React、Vue），需安装 Node.js（建议 LTS 版本）：

步骤：
1. 访问 Node.js 官网（https://nodejs.org/），下载 LTS 版本（如 20.11.1），运行安装程序（勾选"Add to PATH"）。
2. 验证安装：
  bash 复制代码
```
node -v  # 输出 Node.js 版本（如 v20.11.1）
npm -v   # 输出 npm 版本（如 10.8.2）
```
注意：
- 推荐使用 nvm-windows（Node 版本管理器）管理多版本 Node.js，避免版本冲突。

5. 创建并运行 Tauri 项目

使用 Tauri 脚手架快速创建项目：

步骤：
1. 打开终端，运行以下命令创建项目（以 Vanilla JS 模板为例）：
  bash 复制代码
```
npm create tauri-app@latest my-tauri-app -- --template vanilla
```
2. 进入项目目录，安装依赖：
  bash 复制代码
```
cd my-tauri-app
npm install
```
3. 启动开发服务器：
  bash 复制代码
```
npm run tauri dev
```
- 此时会打开一个 Tauri 窗口，显示"Hello, Tauri!"，说明环境安装成功。

二、常见问题与解决方法

以下是 Tauri 安装及编译过程中常见的问题及解决方案：

1. Rust 安装超时

问题：运行 rustup-init.exe 时，下载 Rust 组件超时（如 channel-rust-stable.toml 下载失败）。
原因：网络连接不畅，无法访问 Rust 官方服务器。
解决：
- 设置国内镜像（如 rsproxy.cn），再重新运行安装程序：
  bash 复制代码
```
$env:RUSTUP_DIST_SERVER="https://rsproxy.cn"
$env:RUSTUP_UPDATE_ROOT="https://rsproxy.cn/rustup"
.\rustup-init.exe
```
- 或手动下载 Rust 安装包（https://forge.rust-lang.org/infra/other-installation-methods.html），离线安装。

2. 编译时提示"缺少 C++ 构建工具"

问题：运行 npm run tauri build 时，报错"could not find native static library kernel32"或"MSVC 工具链未安装"。
原因：未安装 Visual Studio Build Tools，或工具链未正确配置。
解决：
- 重新安装 Visual Studio Build Tools，确保勾选"使用 C++ 的桌面开发"。
- 验证 cl.exe 是否可用（运行 cl.exe，输出 MSVC 版本）。

3. 运行时提示"缺少 WebView2"

问题：启动 Tauri 应用时，窗口空白，或提示"无法加载 WebView2"。
原因：系统未安装 WebView2 运行时。
解决：
- 手动下载 WebView2 运行时（https://developer.microsoft.com/zh-cn/microsoft-edge/webview2/），安装后重启应用。

4. 应用启动后无窗口显示

问题：运行 npm run tauri dev 后，终端显示"Server running at http://localhost:5173"，但无窗口弹出。
原因：
- 窗口配置错误（如 tauri.conf.json 中的 windows 配置有误）；
- DPI 缩放问题（Windows 11 高 DPI 设置导致窗口无法显示）。
解决：
- 检查 tauri.conf.json 中的窗口配置（如 width、height 是否合理）；
- 在 tauri.conf.json 中添加 DPI 感知配置：
  json 复制代码
```
{
  "tauri": {
    "windows": [
      {
        "dpiAware": "permonitorv2"
      }
    ]
  }
}
```
- 启用 Tauri 详细日志（运行 TAURI_LOG=debug npm run tauri dev），查看窗口创建错误信息。

5. 无装饰窗口无法调整大小

问题：设置 decorations: false（无装饰窗口）后，窗口边框无法拖动调整大小。
原因：Tauri 无装饰窗口的调整大小功能依赖透明边框区域，高 DPI 下边框计算错误。
解决：
- 修改 Tauri 源码中的 undecorated_resizing.rs（位于 node_modules/@tauri-apps/cli/node_modules/tauri-runtime-wry/src/undecorated_resizing.rs），修复高 DPI 下的边框计算：
  rust 复制代码
```
// 替换原有的边框计算逻辑
let border_x = (border_x as f64 * dpi as f64 / 96.0) as i32;
let border_y = (border_y as f64 * dpi as f64 / 96.0) as i32;
```
- 或升级 Tauri 到最新版本（2.0+），官方已修复此问题。

6. 拖动窗口卡顿（Acrylic 特效）

问题：使用 window-vibrancy 插件添加 Acrylic 特效后，拖动窗口卡顿。
原因：Windows 11 某些版本（如 build 22621+）对 Acrylic 特效的拖动性能优化不佳。

解决：

检测 Windows 版本，若为有性能问题的版本，拖动时暂时清除 Acrylic 特效，拖动结束后恢复：

javascript 复制代码

import { platform, version } from '@tauri-apps/api/os';

const hasAcrylicPerformanceIssue = () => {
  const [major, minor, build] = version().split('.').map(Number);
  // Windows 11 build 22621+ 有性能问题
  return major === 10 && minor === 0 && build >= 22621;
};

// 拖动开始时清除特效
const handleDragStart = () => {
  if (hasAcrylicPerformanceIssue()) {
    clearWindowAcrylic();
  }
};

// 拖动结束后恢复特效
const handleDragEnd = () => {
  if (hasAcrylicPerformanceIssue()) {
    applyWindowAcrylic();
  }
};

或使用 Mica 特效（Windows 11 专属，性能更好）：
javascript 复制代码
```
import { applyMica } from 'window-vibrancy';
applyMica(window);
```

三、总结

Tauri 开发环境安装的核心是 Rust 工具链 、C++ 构建工具 和 WebView2 运行时 ，需确保这些组件正确安装。常见问题主要集中在 网络超时 、工具链配置 和 窗口渲染，通过本文提供的解决方法，可快速定位并修复问题。

若需更深入的帮助，可参考 Tauri 官方文档（https://tauri.app/docs/）或社区论坛（https://github.com/tauri-apps/tauri/discussions）。