migrating-tauri-apps

Tauri 迁移指南

本指南介绍如何将 Tauri 应用从 v1 或 v2 beta 迁移到 v2 stable。

迁移路径

源版本	目标版本	复杂度
Tauri v1.x	v2 stable	高 - 存在重大破坏性变更
Tauri v2 beta	v2 stable	低 - 存在少量破坏性变更

---

自动迁移

这两种迁移路径都支持通过 Tauri CLI 自动迁移：

# Install latest CLI first
npm install @tauri-apps/cli@latest

# Run migration
npm run tauri migrate
# or: yarn tauri migrate | pnpm tauri migrate | cargo tauri migrate

重要： migrate 命令可以自动完成大多数任务，但不能完全替代手动检查。运行后务必验证所做的更改。

---

从 v1 迁移到 v2

配置文件变更

破坏性变更：顶层结构变更

之前（v1）：

{
  "package": {
    "productName": "my-app",
    "version": "1.0.0"
  },
  "tauri": {
    "bundle": { ... },
    "allowlist": { ... }
  }
}

之后（v2）：

{
  "productName": "my-app",
  "version": "1.0.0",
  "mainBinaryName": "my-app",
  "identifier": "com.example.myapp",
  "app": { ... },
  "bundle": { ... }
}

键名重命名

v1 路径	v2 路径
package.productName	productName（顶层）
package.version	version（顶层）
tauri	app
tauri.bundle	bundle（顶层）
tauri.bundle.identifier	identifier（顶层）
tauri.systemTray	app.trayIcon
build.distDir	frontendDist
build.devPath	devUrl

破坏性变更：新增必需字段

添加与 productName 匹配的 mainBinaryName——该字段不再自动设置：

{
  "productName": "My App",
  "mainBinaryName": "My App"
}

Bundle 配置重组

平台专属的 bundle 配置已移至对应的平台键下：

之前：

{
  "tauri": {
    "bundle": {
      "dmg": { ... },
      "deb": { ... }
    }
  }
}

之后：

{
  "bundle": {
    "macOS": {
      "dmg": { ... }
    },
    "linux": {
      "deb": { ... }
    }
  }
}

更新器配置

如果使用应用更新器，请将以下配置添加到 bundle 配置中：

{
  "bundle": {
    "createUpdaterArtifacts": "v1Compatible"
  }
}

现有发行版请使用 "v1Compatible"，以保持向后兼容性。

---

破坏性变更：Allowlist 已由 Capabilities 取代

v1 的 allowlist 系统已完全由基于 capability 的 ACL 系统取代。

创建 Capabilities

在 src-tauri/capabilities/ 中创建 JSON 文件：

src-tauri/capabilities/default.json：

{
  "identifier": "default",
  "description": "Default capabilities for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "shell:allow-open",
    "dialog:allow-open",
    "fs:allow-read-text-file"
  ]
}

tauri migrate 命令会根据 v1 allowlist 自动生成 capabilities。

---

Cargo.toml 变更

已移除的功能

以下功能在 v2 中已不存在：

• reqwest-client
• reqwest-native-tls-vendored
• process-command-api
• shell-open-api
• windows7-compat
• updater
• system-tray

新增功能

• linux-protocol-body - 支持解析自定义协议请求体

破坏性变更：API 模块移除

整个 api 模块已移除。相关功能已移至插件：

v1 API	v2 替代方案
tauri::api::dialog	tauri-plugin-dialog
tauri::api::http	tauri-plugin-http
tauri::api::process	tauri-plugin-process
tauri::api::path 函数	tauri::Manager::path

破坏性变更：Rust API 变更

已移除的 API

v1	v2 替代方案
App::clipboard_manager	tauri-plugin-clipboard-manager
App::global_shortcut_manager	tauri-plugin-global-shortcut
App::get_cli_matches	tauri-plugin-cli
tauri::updater	tauri-plugin-updater

类型／方法重命名

v1	v2
Window	WebviewWindow
Manager::get_window	Manager::get_webview_window

菜单 API 变更

之前：

use tauri::{Menu, CustomMenuItem};
let menu = Menu::new()
    .add_item(CustomMenuItem::new("quit", "Quit"));

之后：

use tauri::menu::{MenuBuilder, MenuItemBuilder};
let menu = MenuBuilder::new(app)
    .item(&MenuItemBuilder::with_id("quit", "Quit").build(app)?)
    .build()?;

托盘 API 变更

之前：

use tauri::SystemTray;
SystemTray::new().with_menu(menu);

之后：

use tauri::tray::TrayIconBuilder;
TrayIconBuilder::new()
    .menu(&menu)
    .on_menu_event(|app, event| { ... })
    .on_tray_icon_event(|tray, event| { ... })
    .build(app)?;

---

破坏性变更：JavaScript API 变更

包名重命名

v1	v2
@tauri-apps/api/tauri	@tauri-apps/api/core
@tauri-apps/api/window	@tauri-apps/api/webviewWindow

核心 API 精简

核心 @tauri-apps/api 包现在仅包含：

• core
• path
• event
• webviewWindow

所有其他 API 都需要使用插件包。

---

重大变更：插件迁移

所有以前内置的 API 现在都是独立插件：

v1 导入	v2 插件包
@tauri-apps/api/cli	@tauri-apps/plugin-cli
@tauri-apps/api/clipboard	@tauri-apps/plugin-clipboard-manager
@tauri-apps/api/dialog	@tauri-apps/plugin-dialog
@tauri-apps/api/fs	@tauri-apps/plugin-fs
@tauri-apps/api/global-shortcut	@tauri-apps/plugin-global-shortcut
@tauri-apps/api/http	@tauri-apps/plugin-http
@tauri-apps/api/notification	@tauri-apps/plugin-notification
@tauri-apps/api/os	@tauri-apps/plugin-os
@tauri-apps/api/process	@tauri-apps/plugin-process
@tauri-apps/api/shell	@tauri-apps/plugin-shell
@tauri-apps/api/updater	@tauri-apps/plugin-updater

安装插件

# JavaScript
npm install @tauri-apps/plugin-fs

# Rust (add to Cargo.toml)
cargo add tauri-plugin-fs

在 Rust 代码中注册插件：

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_fs::init())
        .run(tauri::generate_context!())
        .expect("error running app");
}

重大变更：文件系统插件变更

@tauri-apps/plugin-fs 中的函数重命名：

v1	v2
createDir	mkdir
readBinaryFile	readFile
writeBinaryFile	writeFile
removeDir	remove
removeFile	remove
renameFile	rename
Dir enum	BaseDirectory

重大变更：事件系统变更

v1	v2
emit()	向所有监听器广播（行为变更）
不适用	emit_to() - 指定目标事件接收方
listen_global	listen_any

重大变更：Windows 源 URL

生产环境中的 Windows 应用现在通过 http://tauri.localhost 而非 https:// 提供服务。

影响： 除非保留旧行为，否则 IndexedDB 和 Cookie 将被重置：

{
  "app": {
    "windows": [{
      "useHttpsScheme": true
    }]
  }
}

重大变更：环境变量

v1	v2
TAURI_PRIVATE_KEY	TAURI_SIGNING_PRIVATE_KEY
TAURI_KEY_PASSWORD	TAURI_SIGNING_PRIVATE_KEY_PASSWORD
TAURI_DEV_SERVER_PORT	TAURI_CLI_PORT
平台变量	现在以 TAURI_ENV_ 为前缀

移动端支持设置

若要同时支持移动端和桌面端：

1. 更新 Cargo.toml：

[lib]
name = "app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]

2. 将 src/main.rs 重命名为 src/lib.rs：

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .run(tauri::generate_context!())
        .expect("error running app");
}

3. 创建新的 src/main.rs：

fn main() {
    app_lib::run();
}

---

从 V2 Beta 迁移到 V2 Stable

重大变更：核心权限前缀

所有核心权限现在都需要 "core:" 前缀：

之前（Beta）：

{
  "permissions": [
    "path:default",
    "event:default",
    "window:default"
  ]
}

之后（Stable）：

{
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default"
  ]
}

简化方案： 使用 "core:default" 以包含所有默认核心权限：

{
  "permissions": ["core:default"]
}

---

重大变更：移动端开发服务器配置

移动端开发服务器不再向网络开放。流量通过隧道直接从本地计算机传输到设备。

之前（Beta）：

const mobile = !!/android|ios/.exec(process.env.TAURI_ENV_PLATFORM);
export default {
  server: {
    host: mobile ? '0.0.0.0' : false
  }
};

之后（Stable）：

const host = process.env.TAURI_DEV_HOST;
export default {
  server: {
    host: host || false
  }
};

如果之前使用了 internal-ip NPM 包，请移除对它的依赖。

iOS 设备开发： 需要额外步骤。使用：

tauri ios dev --force-ip-prompt

出现提示时，选择设备的 TUN 地址。

---

迁移检查清单

从 V1 迁移到 V2

• 运行 npm run tauri migrate
• 验证配置结构变更（package -> 顶层）
• 添加 mainBinaryName 字段
• 更新 bundle 配置结构
• 将 allowlist 替换为 capabilities
• 安装所需插件
• 更新 Rust 导入（Window -> WebviewWindow）
• 更新 JS 导入（@tauri-apps/api/tauri -> core）
• 如果使用 fs 插件，更新 FS 函数名称
• 更新环境变量名称
• 测试事件系统行为
• 验证 Windows 源 URL 处理方式（IndexedDB/Cookie）
• 如果使用了菜单/托盘代码，请更新
• 移除已弃用的 Cargo 功能

从 V2 Beta 迁移到 V2 Stable

• 运行 npm run tauri migrate
• 为权限标识符添加 core: 前缀（或使用 core:default）
• 更新移动端开发服务器配置
• 如果存在 internal-ip 包依赖，请移除
• 使用 --force-ip-prompt 测试 iOS 设备开发

---

常见问题

问题	解决方案
权限被拒绝错误	检查 src-tauri/capabilities/ 文件，确认所需权限
IndexedDB/localStorage 丢失（Windows）	在窗口配置中设置 useHttpsScheme: true
找不到插件	将其添加到 Cargo.toml，通过 .plugin() 注册，并安装 npm 包
移动端构建失败	检查 Cargo.toml 中的 [lib] 部分，以及带有移动端入口点的 src/lib.rs