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

バンドル設定の再編成

プラットフォーム固有のバンドル設定は、それぞれのプラットフォームキーの下に移動しました。

変更前：

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

変更後：

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

アップデーターの設定

アプリのアップデーターを使用している場合は、バンドル設定に追加してください。

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

既存の配布物との後方互換性を維持するには、"v1Compatible" を使用してください。

---

破壊的変更：Allowlist が Capabilities に置き換え

v1 の Allowlist システムは、Capabilities ベースの 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()	すべてのリスナーにブロードキャストします（動作の変更）
N/A	emit_to() - 特定のイベントターゲットを指定します
listen_global	listen_any

重大な変更：Windows のオリジン URL

Windows の本番アプリは、https:// ではなく http://tauri.localhost から配信されるようになりました。

影響： 古い動作を維持しない限り、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 ベータ版から V2 安定版への移行

重大な変更：コア権限のプレフィックス

すべてのコア権限に "core:" プレフィックスが必要になりました。

変更前（ベータ版）：

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

変更後（安定版）：

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

簡略化した方法： "core:default" を使用すると、すべてのデフォルトのコア権限が含まれます。

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

---

重大な変更：モバイル開発サーバーの設定

モバイル開発サーバーはネットワーク越しに公開されなくなりました。トラフィックはローカルマシンからデバイスへ直接トンネルされます。

変更前（ベータ版）：

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

変更後（安定版）：

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 ベータ版から V2 安定版への移行

• 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 を確認してください