Tauri升级指南：从旧版本迁移到新版本

Tauri升级指南：从旧版本迁移到新版本

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

引言

Tauri作为一款轻量级跨平台桌面应用开发框架，以其更小的应用体积、更快的运行速度和更强的安全性，正在获得越来越多开发者的青睐。随着Tauri版本的不断迭代，新功能和性能优化不断涌现，但版本升级也带来了迁移挑战。本文将详细介绍Tauri从旧版本迁移到新版本的完整流程，帮助开发者平稳过渡，充分利用新版本特性。

升级前准备

环境检查

在开始升级前，需要确保开发环境满足新版本Tauri的要求。以下是主要环境依赖项的最低版本要求：

依赖项	最低版本	推荐版本
Node.js	16.0.0	18.0.0+
Rust	1.63.0	1.70.0+
Cargo	1.63.0	1.70.0+
npm	7.0.0	8.0.0+
pnpm	6.0.0	7.0.0+

检查当前环境版本的命令：

node -v
rustc -vV
cargo -V
npm -v
pnpm -v

项目备份

升级前务必备份项目，推荐使用Git进行版本控制：

# 创建升级分支
git checkout -b tauri-upgrade
# 提交当前更改
git add .
git commit -m "Backup before Tauri upgrade"

也可以创建项目的压缩备份：

# 创建项目备份
zip -r tauri-backup.zip . -x "*.git/*" "node_modules/*" "target/*"

升级流程

1. 更新Tauri CLI

首先更新全局Tauri CLI：

# 使用npm
npm install -g @tauri-apps/cli

# 使用pnpm
pnpm add -g @tauri-apps/cli

# 验证安装版本
tauri --version

2. 更新项目依赖

更新package.json中的Tauri相关依赖：

{
  "devDependencies": {
    "@tauri-apps/cli": "^2.8.0",
    "@tauri-apps/api": "^2.8.0"
  }
}

安装更新：

# 使用npm
npm install

# 使用pnpm
pnpm install

3. 更新Cargo依赖

更新src-tauri/Cargo.toml中的Tauri依赖：

[package]
name = "tauri-app"
version = "0.1.0"
description = ""
authors = ["Your Name"]
license = ""
repository = ""
edition = "2021"

[dependencies]
tauri = { version = "2.8.0", features = ["api-all"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

更新依赖：

cd src-tauri
cargo update
cd ..

4. 运行迁移命令

Tauri提供了自动迁移工具，可处理大部分配置文件的更新：

tauri migrate

主要版本变更及迁移要点

从v1到v2的核心变更

Tauri 2.0引入了多项重大变更，以下是需要重点关注的迁移点：

1. 配置文件结构调整

Tauri 2.0对配置文件tauri.conf.json进行了结构调整，主要变更：

• tauri.bundle重命名为tauri.build
• tauri.window配置移动到tauri.windows数组
• 新增capabilities配置项，用于权限管理

旧版本配置示例(v1.x)：

{
  "tauri": {
    "bundle": {
      "identifier": "com.example.app",
      "name": "My Tauri App"
    },
    "window": {
      "title": "My Tauri App",
      "width": 800,
      "height": 600
    }
  }
}

新版本配置示例(v2.x)：

{
  "tauri": {
    "build": {
      "identifier": "com.example.app",
      "productName": "My Tauri App"
    },
    "windows": [
      {
        "title": "My Tauri App",
        "width": 800,
        "height": 600,
        "label": "main"
      }
    ],
    "capabilities": ["default"]
  }
}

2. 权限系统变更

Tauri 2.0引入了新的权限系统，需要在tauri.conf.json中显式声明：

{
  "tauri": {
    "capabilities": ["default", "fs-read", "fs-write"],
    "permissions": {
      "fs": {
        "all": true,
        "readFile": true,
        "writeFile": true,
        "scope": ["$HOME/*", "$APP/*"]
      }
    }
  }
}

3. Rust API变更

Tauri 2.0对Rust API进行了多项调整，主要变更点：

• tauri::Builder的使用方式
• 命令注册方式变更
• 窗口管理API调整

旧版本Rust代码(v1.x)：

use tauri::Manager;

fn main() {
  tauri::Builder::default()
    .setup(|app| {
      let main_window = app.get_window("main").unwrap();
      Ok(())
    })
    .invoke_handler(tauri::generate_handler![my_command])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

#[tauri::command]
fn my_command() -> String {
  "Hello from Tauri!".into()
}

新版本Rust代码(v2.x)：

use tauri::Manager;

fn main() {
  tauri::Builder::default()
    .setup(|app| {
      let main_window = app.get_webview_window("main").unwrap();
      Ok(())
    })
    .command(my_command)
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

#[tauri::command]
fn my_command() -> String {
  "Hello from Tauri!".into()
}

4. JavaScript API变更

Tauri 2.0的JavaScript API也有部分调整：

• 模块导入路径变更
• 窗口操作API调整
• 事件系统优化

旧版本JavaScript代码(v1.x)：

import { invoke } from '@tauri-apps/api/tauri';
import { getCurrentWindow } from '@tauri-apps/api/window';

// 调用命令
invoke('my_command').then(result => console.log(result));

// 窗口操作
const window = getCurrentWindow();
window.setTitle('New Title');

新版本JavaScript代码(v2.x)：

import { invoke } from '@tauri-apps/api/core';
import { WebviewWindow } from '@tauri-apps/api/webviewWindow';

// 调用命令
invoke('my_command').then(result => console.log(result));

// 窗口操作
const window = WebviewWindow.getCurrent();
window.setTitle('New Title');

常见问题及解决方案

1. 编译错误：找不到tauri::generate_context!

问题描述：升级后编译Rust代码时出现错误：error: cannot find macro 'generate_context!' in this scope

解决方案：Tauri 2.0中generate_context!宏已移至tauri_build crate，需要更新build.rs：

// src-tauri/build.rs
fn main() {
  tauri_build::build()
}

2. 运行时错误：窗口无法创建

问题描述：应用启动后无法创建窗口，日志显示window not found: main

解决方案：Tauri 2.0要求在配置文件中显式定义窗口：

{
  "tauri": {
    "windows": [
      {
        "label": "main",
        "title": "My Tauri App",
        "width": 800,
        "height": 600,
        "url": "index.html"
      }
    ]
  }
}

3. API调用错误：invoke函数未找到

问题描述：JavaScript中调用invoke时出现错误：Uncaught TypeError: Cannot read properties of undefined (reading 'invoke')

解决方案：Tauri 2.0中invoke函数的导入路径已变更：

// 旧版本
import { invoke } from '@tauri-apps/api/tauri';

// 新版本
import { invoke } from '@tauri-apps/api/core';

4. 权限错误：无法读取文件系统

问题描述：应用运行时出现文件系统访问权限错误

解决方案：在Tauri 2.0中需要显式声明权限：

{
  "tauri": {
    "capabilities": ["default", "fs-read"],
    "permissions": {
      "fs": {
        "readFile": true,
        "scope": ["$HOME/Documents/*"]
      }
    }
  }
}

迁移验证

本地测试

完成迁移后，进行本地测试验证：

# 开发模式运行
tauri dev

# 构建生产版本
tauri build

# 运行生产版本
# Windows
target/release/your-app.exe
# macOS
target/release/your-app.app/Contents/MacOS/your-app
# Linux
target/release/your-app

功能测试清单

创建测试清单，验证关键功能是否正常工作：

1. 窗口管理

   • 窗口创建/关闭
   • 窗口大小调整
   • 窗口标题修改

2. API调用

   • Rust命令调用
   • 文件系统访问
   • 系统对话框

3. 事件系统

   • 窗口事件
   • 自定义事件
   • 事件监听/取消监听

4. 性能测试

   • 启动时间
   • 内存占用
   • CPU使用率

高级迁移场景

插件迁移

如果项目使用了Tauri插件，需要确保插件与新版本兼容：

# 更新官方插件
cargo add tauri-plugin-store@2.0.0
cargo add tauri-plugin-dialog@2.0.0

# 更新npm插件
npm install @tauri-apps/plugin-store@2.0.0

自定义协议迁移

Tauri 2.0中自定义协议的注册方式有所变更：

// 旧版本
tauri::Builder::default()
  .register_uri_scheme_protocol("myapp", |app, request| {
    // 处理协议请求
    Ok(tauri::Response::new(200, "text/plain", "Hello from custom protocol".as_bytes().to_vec()))
  })

// 新版本
tauri::Builder::default()
  .protocol("myapp", |app, request| {
    // 处理协议请求
    Ok(tauri::Response::new(200, "text/plain", "Hello from custom protocol".as_bytes().to_vec()))
  })

移动平台支持

Tauri 2.0增强了移动平台支持，如需迁移到移动平台：

# 初始化移动支持
tauri android init
tauri ios init

# 构建移动应用
tauri android build
tauri ios build

总结与后续步骤

完成Tauri版本升级后，建议：

1. 全面测试：在所有目标平台上进行全面测试
2. 性能分析：使用tauri dev --profile=release分析性能变化
3. 文档更新：更新项目文档中的Tauri相关部分
4. 依赖清理：移除不再需要的旧依赖
5. 监控日志：关注应用运行日志，及时发现潜在问题

Tauri团队持续改进框架，建议定期查看官方更新日志，及时获取最新特性和安全更新。

附录：迁移流程图

附录：版本变更速查表

功能	旧版本(v1.x)	新版本(v2.x)
配置文件	tauri.bundle	tauri.build
窗口配置	tauri.window	tauri.windows数组
命令注册	invoke_handler(generate_handler![])	.command()方法链
窗口获取	app.get_window()	app.get_webview_window()
invoke导入	@tauri-apps/api/tauri	@tauri-apps/api/core
权限系统	隐式权限	显式capabilities配置

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