migrating-tauri-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tauri Migration Guide

Tauri迁移指南

This skill covers migrating Tauri applications to v2 stable from either v1 or v2 beta.

本指南涵盖将Tauri应用从v1或v2测试版迁移到v2稳定版的内容。

Migration Paths

迁移路径

Source Version	Target	Complexity
Tauri v1.x	v2 stable	High - significant breaking changes
Tauri v2 beta	v2 stable	Low - minor breaking changes

源版本	目标版本	复杂度
Tauri v1.x	v2稳定版	高 - 存在重大破坏性变更
Tauri v2测试版	v2稳定版	低 - 仅存在轻微破坏性变更

Automated Migration

自动化迁移

Both migration paths support automated migration via the Tauri CLI:

bash

undefined

两种迁移路径均支持通过Tauri CLI进行自动化迁移：

bash

undefined

Install latest CLI first

先安装最新版CLI

npm install @tauri-apps/cli@latest

Run migration

运行迁移命令

npm run tauri migrate

or: yarn tauri migrate | pnpm tauri migrate | cargo tauri migrate

或：yarn tauri migrate | pnpm tauri migrate | cargo tauri migrate


**IMPORTANT:** The migrate command automates most tasks but is NOT a complete substitute for manual review. Always verify changes after running.

---


**重要提示：** 迁移命令可自动完成大部分任务，但无法完全替代人工检查。运行后请务必验证所有变更。

---

V1 to V2 Migration

从V1迁移到V2

Configuration File Changes

配置文件变更

BREAKING: Top-Level Structure Changes

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

Before (v1):

json

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

After (v2):

json

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

V1版本：

json

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

V2版本：

json

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

Key Renames

关键项重命名

v1 Path	v2 Path
`package.productName`	`productName` (top-level)
`package.version`	`version` (top-level)
`tauri`	`app`
`tauri.bundle`	`bundle` (top-level)
`tauri.bundle.identifier`	`identifier` (top-level)
`tauri.systemTray`	`app.trayIcon`
`build.distDir`	`frontendDist`
`build.devPath`	`devUrl`

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`

BREAKING: New Required Field

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

Add

mainBinaryName

matching your

productName

- this is no longer automatic:

json

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

添加与

productName

一致的

mainBinaryName

字段 - 该字段不再自动生成：

json

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

Bundle Configuration Reorganization

打包配置重组

Platform-specific bundle configs moved under their platform key:

Before:

json

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

After:

json

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

平台特定的打包配置已移至对应平台的键下：

之前：

json

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

之后：

json

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

Updater Configuration

更新器配置

If using the app updater, add to bundle config:

json

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

Use

"v1Compatible"

for existing distributions to maintain backward compatibility.

如果使用应用更新器，请在打包配置中添加以下内容：

json

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

对于现有分发版本，使用

"v1Compatible"

以保持向后兼容性。

BREAKING: Allowlist Replaced with Capabilities

破坏性变更：权限列表替换为能力系统

The v1 allowlist system is completely replaced with a capability-based ACL system.

V1版本的权限列表系统已完全被基于能力的ACL系统取代。

Creating Capabilities

创建能力配置

Create JSON files in

src-tauri/capabilities/

src-tauri/capabilities/default.json:

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"
  ]
}

The

tauri migrate

command auto-generates capabilities from your v1 allowlist.

在

src-tauri/capabilities/

目录下创建JSON文件：

src-tauri/capabilities/default.json：

json

{
  "identifier": "default",
  "description": "主窗口的默认权限",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "shell:allow-open",
    "dialog:allow-open",
    "fs:allow-read-text-file"
  ]
}

tauri migrate

命令会从你的V1权限列表自动生成能力配置。

Cargo.toml Changes

Cargo.toml变更

Removed Features

移除的特性

These features no longer exist in v2:

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

以下特性在V2中已不再存在：

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

New Features

新增特性

```
linux-protocol-body
```
- Custom protocol request body parsing support

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

BREAKING: API Module Removal

破坏性变更：API模块移除

The entire

api

module is removed. Functionality moved to plugins:

v1 API	v2 Replacement
`tauri::api::dialog`	`tauri-plugin-dialog`
`tauri::api::http`	`tauri-plugin-http`
`tauri::api::process`	`tauri-plugin-process`
`tauri::api::path` functions	`tauri::Manager::path`

整个

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`

BREAKING: Rust API Changes

破坏性变更：Rust API变更

Removed APIs

移除的API

v1	v2 Alternative
`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替代方案
`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`

Renamed Types/Methods

重命名的类型/方法

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

V1	V2
`Window`	`WebviewWindow`
`Manager::get_window`	`Manager::get_webview_window`

Menu API Changes

菜单API变更

Before:

rust

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

After:

rust

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

之前：

rust

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

之后：

rust

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

Tray API Changes

托盘API变更

Before:

rust

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

After:

rust

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

之前：

rust

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

之后：

rust

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

BREAKING: JavaScript API Changes

破坏性变更：JavaScript API变更

Package Renames

包重命名

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

V1	V2
`@tauri-apps/api/tauri`	`@tauri-apps/api/core`
`@tauri-apps/api/window`	`@tauri-apps/api/webviewWindow`

Core API Reduction

核心API精简

The core

@tauri-apps/api

package now only includes:

```
core
```
```
path
```
```
event
```
```
webviewWindow
```

All other APIs require plugin packages.

核心

@tauri-apps/api

包现在仅包含：

```
core
```
```
path
```
```
event
```
```
webviewWindow
```

所有其他API需要单独安装插件包。

BREAKING: Plugin Migration

破坏性变更：插件迁移

All formerly built-in APIs are now separate plugins:

v1 Import	v2 Plugin Package
`@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`

所有原内置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`

Installing Plugins

安装插件

bash

undefined

bash

undefined

JavaScript

npm install @tauri-apps/plugin-fs

Rust (add to Cargo.toml)

Rust（添加到Cargo.toml）

cargo add tauri-plugin-fs


Register plugins in your Rust code:

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

cargo add tauri-plugin-fs


在Rust代码中注册插件：

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

BREAKING: File System Plugin Changes

破坏性变更：文件系统插件变更

Function renames in

@tauri-apps/plugin-fs

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

@tauri-apps/plugin-fs

中的函数重命名：

V1	V2
`createDir`	`mkdir`
`readBinaryFile`	`readFile`
`writeBinaryFile`	`writeFile`
`removeDir`	`remove`
`removeFile`	`remove`
`renameFile`	`rename`
`Dir` 枚举	`BaseDirectory`

BREAKING: Event System Changes

破坏性变更：事件系统变更

v1	v2
`emit()`	Broadcasts to ALL listeners (behavior change)
N/A	`emit_to()` - target specific event targets
`listen_global`	`listen_any`

V1	V2
`emit()`	广播至所有监听器（行为变更）
无	`emit_to()` - 定向发送至特定事件目标
`listen_global`	`listen_any`

BREAKING: Windows Origin URL

破坏性变更：Windows平台源URL

Production Windows apps now serve from

http://tauri.localhost

instead of

https://

Impact: IndexedDB and cookies will reset unless you preserve the old behavior:

json

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

Windows平台的生产环境应用现在从

http://tauri.localhost

提供服务，而非原有的

https://

。

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

json

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

BREAKING: Environment Variables

破坏性变更：环境变量

v1	v2
`TAURI_PRIVATE_KEY`	`TAURI_SIGNING_PRIVATE_KEY`
`TAURI_KEY_PASSWORD`	`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`
`TAURI_DEV_SERVER_PORT`	`TAURI_CLI_PORT`
Platform variables	Now prefixed `TAURI_ENV_`

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_`

Mobile Support Setup

移动端支持设置

To target mobile alongside desktop:

1. Update Cargo.toml:

toml

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

2. Rename src/main.rs to src/lib.rs:

rust

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

3. Create new src/main.rs:

rust

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

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

1. 更新Cargo.toml：

toml

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

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

rust

#[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：

rust

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

V2 Beta to V2 Stable Migration

从V2测试版迁移到V2稳定版

BREAKING: Core Permission Prefix

破坏性变更：核心权限前缀

All core permissions now require the

"core:"

prefix:

Before (beta):

json

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

After (stable):

json

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

Simplified alternative: Use

"core:default"

to include all default core permissions:

json

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

所有核心权限现在需要添加

"core:"

前缀：

测试版：

json

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

稳定版：

json

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

简化方案： 使用

"core:default"

来包含所有默认核心权限：

json

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

BREAKING: Mobile Dev Server Configuration

破坏性变更：移动端开发服务器配置

The mobile development server no longer exposes across networks. Traffic tunnels directly from local machine to devices.

Before (beta):

javascript

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

After (stable):

javascript

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

Remove dependency on the

internal-ip

NPM package if previously used.

iOS Device Development: Requires additional steps. Use:

bash

tauri ios dev --force-ip-prompt

Select the device's TUN address when prompted.

移动端开发服务器不再暴露至网络，流量将直接从本地机器隧道传输至设备。

测试版：

javascript

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

稳定版：

javascript

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

如果之前使用了

internal-ip

npm包，请移除该依赖。

iOS设备开发： 需要额外步骤，使用以下命令：

bash

tauri ios dev --force-ip-prompt

在提示时选择设备的TUN地址。

Migration Checklist

迁移检查清单

V1 to V2

V1到V2

Run
```
npm run tauri migrate
```
Verify config structure changes (package -> top-level)
Add
```
mainBinaryName
```
field
Update bundle config structure
Replace allowlist with capabilities
Install required plugins
Update Rust imports (Window -> WebviewWindow)
Update JS imports (@tauri-apps/api/tauri -> core)
Update FS function names if using fs plugin
Update environment variable names
Test event system behavior
Verify Windows origin URL handling (IndexedDB/cookies)
Update menu/tray code if used
Remove deprecated Cargo features

运行
```
npm run tauri migrate
```
验证配置结构变更（package字段移至顶层）
添加
```
mainBinaryName
```
字段
更新打包配置结构
用能力系统替换权限列表
安装所需插件
更新Rust导入（Window -> WebviewWindow）
更新JS导入（@tauri-apps/api/tauri -> core）
若使用fs插件，更新文件系统函数名称
更新环境变量名称
测试事件系统行为
验证Windows平台源URL处理（IndexedDB/Cookie）
若使用菜单/托盘，更新对应代码
移除已废弃的Cargo特性

V2 Beta to V2 Stable

V2测试版到V2稳定版

Run
```
npm run tauri migrate
```
Add
```
core:
```
prefix to permission identifiers (or use
```
core:default
```
)
Update mobile dev server configuration
Remove
```
internal-ip
```
package dependency if present
Test iOS device development with
```
--force-ip-prompt
```

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

Common Issues

常见问题

Issue	Solution
Permission denied errors	Check `src-tauri/capabilities/` files for required permissions
IndexedDB/localStorage lost (Windows)	Set `useHttpsScheme: true` in window config
Plugin not found	Add to Cargo.toml, register with `.plugin()` , install npm package
Mobile build fails	Verify `[lib]` section in Cargo.toml and `src/lib.rs` with mobile entry point

问题	解决方案
权限被拒绝错误	检查 `src-tauri/capabilities/` 文件是否包含所需权限
Windows平台IndexedDB/localStorage丢失	在窗口配置中设置 `useHttpsScheme: true`
插件未找到	添加到Cargo.toml，用 `.plugin()` 注册，安装对应npm包
移动端构建失败	验证Cargo.toml中的 `[lib]` 部分和包含移动端入口的 `src/lib.rs`