Contents
スポンサードリンク
移行前の環境チェックと準備
Tauri 2.0 に移行する第一歩は 開発環境が公式推奨バージョンと一致しているか を確認することです。環境不整合は tauri migrate の失敗やビルドエラーの主因となります。このセクションでは、Node・npm、Rust toolchain、Cargo、そして Tauri CLI の最新要件とインストール手順を紹介します。
Node・npm のバージョン確認
Tauri 2.0 は Node ≥ 18.0 と npm ≥ 9.0 を最低要件としています。以下のコマンドで現在のバージョンを確認し、必要に応じてアップデートしてください。
|
1 2 3 |
node -v # 例: v20.12.1 以上か確認 npm -v # 例: 9.8.1 以上か確認 |
アップデート手順（nvm 推奨）
nvm がインストールされていない環境でも、公式スクリプトで簡単に導入できます。
|
1 2 3 4 5 6 7 |
# nvm のインストール (未導入の場合) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 最新 LTS バージョンを取得・使用 nvm install --lts nvm use --lts |
参考：公式ガイド – Node.js のインストールとバージョン管理
Rust toolchain と Cargo の設定
Tauri のバックエンドは Rust でビルドされるため、rustup による最新 stable ツールチェーン が必須です。2026 年時点の推奨バージョンは Rust 1.78+（Cargo 1.78+）です。
|
1 2 3 4 5 6 7 |
# rustup が未インストールなら公式スクリプトで導入 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # stable ツールチェーンをデフォルトに設定し、最新版へ更新 rustup default stable rustup update |
バージョン確認は次の通りです。
|
1 2 3 |
rustc --version # 例: rustc 1.78.0 (2026‑04‑01) cargo -V # 例: cargo 1.78.0 (2026‑04‑01) |
参考：公式ガイド – Rust のインストール
Tauri CLI のインストール・バージョン確認
tauri migrate は Tauri CLI に組み込まれたサブコマンドです。2026‑06 時点での最新安定版は 2.12.0 となっています。以下のいずれかの方法でインストールできます。
グローバルインストール（npm）
|
1 2 3 |
npm i -g @tauri-apps/cli@latest # 自動的に 2.x 系最新が取得される tauri --version # => tauri-cli 2.12.0 |
プロジェクトローカルでの利用（推奨）
CI 環境やチーム開発では、プロジェクトごとに CLI バージョンを固定する方が安全です。
|
1 2 3 4 5 6 |
# devDependency に追加 npm i -D @tauri-apps/cli@2.12.0 # npx でローカル実行（インストール不要） npx @tauri-apps/cli migrate --dry-run |
ポイント：
npxはローカルにインストールされたバイナリを優先的に実行するため、グローバルとローカルのバージョン差異によるトラブルが減ります。
参考：公式ガイド – CLI のインストール方法
tauri migrate コマンドの実行とオプション解説
tauri migrate は旧バージョンから 2.0 への設定・コード変換を自動化する中心ツールです。このセクションでは、基本的な使い方と失敗時に役立つ主要オプションを紹介します。
基本的な tauri migrate の実行手順
プロジェクトルートで以下のコマンドを走らせるだけで、設定ファイルや依存パッケージの自動変換が開始されます。実行中は変更点がログに出力され、失敗した場合は .bak バックアップが生成されます。
|
1 2 3 4 5 6 7 8 |
cd your-tauri-project # 推奨：まず dry‑run で差分だけ確認 tauri migrate --dry-run # 問題なければ本番実行（--force は上書きを許可） tauri migrate --force |
主なオプション
| オプション | 効果 | 使用例 |
|---|---|---|
--dry-run |
変更をファイルに書き込まず、レポートのみ出力。CI の PR ビルドで安全確認に最適。 | tauri migrate --dry-run -vv |
--force |
既存の tauri.config.ts がある場合でも上書きする。手動修正が残っているとエラーになるケースで使用。 |
tauri migrate --force |
-vv |
詳細デバッグログを出力し、原因特定に役立つ。 | tauri migrate -vv |
公式リファレンス：
tauri migrate
ロールバックの基本手順
tauri migrate が失敗した場合は次の流れで元に戻せます。
- Git が有効なら
git checkout .で作業ツリーをリセット。 - 自動生成された
.bakファイル（例：tauri.conf.json.bak）を元に復元。 - 必要に応じて
@tauri-apps/apiのバージョンを v1 系へダウングレードし、ビルドが通るか確認。
|
1 2 3 4 5 |
git checkout . mv src-tauri/tauri.conf.json.bak src-tauri/tauri.conf.json # 例 npm i @tauri-apps/api@^1.5.0 cargo clean && cargo build |
設定ファイル変換と API 変更への対応
Tauri 2.0 では設定ファイルの形式が JSON → TypeScript (ESM) に、またいくつかのコア API がシグネチャや名前空間を刷新しました。このセクションでは自動変換だけではカバーできないポイントと、実際に手を書き換える例を示します。
tauri.conf.json → tauri.config.ts の移行チェックポイント
tauri migrate が生成する雛形は次のようになります（抜粋）。自動生成後は必ず以下項目を手作業で確認してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
import { defineConfig } from '@tauri-apps/cli'; export default defineConfig({ package: { productName: "MyApp", version: "0.1.0" }, tauri: { // 旧 JSON の内容が自動的にマッピングされます bundle: { /* ... */ }, security: { /* ... */ } } }); |
手作業で確認すべき主な項目
| 項目 | 変更点 | 注意ポイント |
|---|---|---|
allowlist → permissions |
名前空間が変わり、権限単位が細分化された。例: window.all は廃止され window.create, window.hide 等を個別指定。 |
旧設定が残っているとビルドエラーになるので必ず置換 |
security.csp |
文字列形式からオブジェクト形式へ変更。例: "default-src 'self'" → { defaultSrc: "'self'" } |
配列・文字列の混在に注意 |
bundle.identifier（macOS） |
必須項目が追加された。フォーマットは逆ドメイン (com.example.myapp) が必須。 |
省略すると notarization エラーになる |
tauri.updater |
設定キー名が一部変更。例: active → enabled |
ドキュメントで最新構造を確認 |
公式ドキュメント：
tauri.config.tsの書き方
代表的な API 変更とコード修正例
1. Window 系 API
| v1 | v2 |
|---|---|
import { appWindow } from '@tauri-apps/api/window';await appWindow.show(); |
import { getCurrent } from '@tauri-apps/api/window';const win = await getCurrent();await win.setVisible(true); // show → setVisible |
2. Dialog 系 API
| v1 | v2 |
|---|---|
import { open } from '@tauri-apps/api/dialog';const file = await open({ multiple: false }); |
import { dialog } from '@tauri-apps/api';const file = await dialog.openFile({ multiple: false }); |
3. CSP（Content Security Policy）
|
1 2 3 4 5 6 7 |
// v1 (tauri.conf.json) { "security": { "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'" } } |
|
1 2 3 4 5 6 7 8 |
// v2 (tauri.config.ts) security: { csp: { defaultSrc: "'self'", scriptSrc: ["'self'", "'unsafe-inline'"] } } |
4. invoke の型安全ラッパー（推奨）
|
1 2 3 4 5 |
import { invoke } from '@tauri-apps/api/core'; type MyPayload = { message: string }; const res = await invoke<string>('my_command', { payload: {} as MyPayload }); |
公式 API リファレンス：https://tauri.app/v2/api/js/
OS 別ビルド手順と注意点
Tauri 2 のマルチプラットフォームビルドは、各 OS が提供するネイティブツールチェーンに依存します。ここでは Windows、macOS（Intel & Apple Silicon）、Linux 各環境での必須前提条件と実際のビルドコマンドをまとめます。
Windows ビルド時の前提条件
| 必要なツール | 推奨バージョン・取得方法 |
|---|---|
| Visual Studio 2022 Build Tools（C++ ワークロード） | VS Installer → 「Desktop development with C++」を選択 |
| Windows SDK 10.0.22631 以上 | 同上で自動インストール |
rustup と Cargo（Rust toolchain） |
前述の手順に従い stable をインストール |
注記：
.NET Desktop Runtimeは Tauri 本体には不要です。Windows ビルドに必須なのは C/C++ コンパイラと Windows SDK のみです。
ビルドコマンド例（PowerShell）
|
1 2 3 4 5 6 7 8 9 10 |
# Rust 側のリリースビルド cargo build --release # Tauri が内部で npm スクリプトを呼び出すので、フロントエンドもビルド npm ci # 依存インストール npm run build # React/Vue/Svelte 等のビルド # Tauri の最終パッケージング tauri build |
macOS（Intel & Apple Silicon） ビルドポイント
| 必要なツール | 入手方法 |
|---|---|
Xcode Command Line Tools (xcode-select --install) |
ターミナル実行 |
| Homebrew（パッケージマネージャ） | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
create-dmg（Notarization 用） |
brew install create-dmg |
Universal2 バイナリの生成例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# aarch64 (Apple Silicon) ビルド cargo build --release --target aarch64-apple-darwin # x86_64 (Intel) ビルド cargo build --release --target x86_64-apple-darwin # 2 バイナリを結合して Universal2 を作成 lipo -create -output target/universal/release/MyApp \ target/aarch64-apple-darwin/release/MyApp \ target/x86_64-apple-darwin/release/MyApp # Tauri が自動で dmg 作成・ notarization（Apple ID 必要） tauri build |
Linux ビルド環境の依存パッケージ
| ディストリビューション | 必要なパッケージ例 |
|---|---|
| Ubuntu 22.04 / Debian | libwebkit2gtk-4.0-dev libsoup-3.0-dev libssl-dev pkg-config clang |
| Fedora 40 | webkit2gtk4.1-devel openssl-devel clang pkgconf-pkg-config |
| Arch Linux | webkit2gtk base-devel openssl clang |
Docker を使ったビルド（公式イメージ）
|
1 2 3 |
docker run --rm -v "$(pwd)":/src -w /src ghcr.io/tauri-apps/tauri-builder:latest \ sh -c "npm ci && npm run build && tauri build" |
参考：https://github.com/tauri-apps/tauri/tree/dev/tools/builder
CI/CD パイプラインへの組み込みと移行後の検証フロー
自動化されたビルド・テストは、チーム全体で安定的に Tauri 2 へ移行する鍵です。ここでは GitHub Actions と GitLab CI の具体例を示し、キャッシュ戦略や失敗時のアーティファクト保存方法も解説します。
GitHub Actions における migrate とビルド自動化
以下は ci.yml（抜粋）です。PR ビルドでは --dry-run のみ実行し、マージ時に本番移行とビルドを走らせます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 |
name: Tauri CI on: push: branches: [ main ] pull_request: jobs: build: runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, macos-14, windows-latest] steps: - uses: actions/checkout@v4 # Node と Cargo のキャッシュ - name: Cache node_modules uses: actions/cache@v3 with: path: ~/.npm key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }} - name: Setup Node uses: actions/setup-node@v4 with: node-version: '18.x' - name: Cache Cargo registry & target uses: actions/cache@v3 with: path: | ~/.cargo/registry ~/.cargo/git target key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }} - name: Install Rust toolchain run: rustup default stable - name: Install Tauri CLI (local) run: npm i -D @tauri-apps/cli@2.12.0 # 1️⃣ PR 用 dry‑run - name: Run Tauri migrate (dry-run) if: github.event_name == 'pull_request' run: npx @tauri-apps/cli migrate --dry-run || true # 2️⃣ main ブランチで本番移行 - name: Apply migration on main if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' run: npx @tauri-apps/cli migrate --force # 3️⃣ ビルド - name: Build Tauri app run: | npm ci npm run build # フロントエンドビルド npx @tauri-apps/cli build # 成果物を保存（各 OS のパッケージ） - uses: actions/upload-artifact@v4 with: name: ${{ runner.os }}-artifact path: src-tauri/target/release/bundle/**/* |
重要ポイント
--dry-runを PR ビルドで実行 → 変更点だけをレビューできる。--forceはmainブランチへのマージ時にのみ実施 → 誤って本番環境に上書きしない。- キャッシュ により Cargo と npm のインストール時間が約 70% 短縮。
GitLab CI の設定例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
stages: - migrate - build variables: NODE_VERSION: "18" CARGO_HOME: "$CI_PROJECT_DIR/.cargo" cache: key: "${CI_JOB_NAME}-${CI_COMMIT_REF_SLUG}" paths: - node_modules/ - .cargo/registry - target/ migrate: stage: migrate image: rust:latest script: - apt-get update && apt-get install -y npm - npm i -D @tauri-apps/cli@2.12.0 - npx @tauri-apps/cli migrate --dry-run # PR 用に差分のみ表示 build: stage: build image: ghcr.io/tauri-apps/tauri-builder:latest script: - npm ci - npm run build - npx @tauri-apps/cli migrate --force # main ブランチで本番適用 - npx @tauri-apps/cli build artifacts: paths: - src-tauri/target/release/bundle/** |
テスト・デバッグ、ロールバック手順
- 単体テスト
bash
npm test # フロントエンド
cargo test --workspace # Rust バックエンド - 統合テスト（Playwright 例）
ビルドしたバイナリを起動し、ウィンドウ生成やダイアログ呼び出しが期待通りか自動チェック。 - ロールバック
Git のリバート →git revert <commit>
.bakファイルから復元 →mv src-tauri/tauri.conf.json.bak src-tauri/tauri.conf.json
CI が失敗した際は、アップロードされたアーティファクト（.exe/.dmg/AppImage）をローカルで実行し、ログとスタックトレースを比較すると原因特定が容易です。
よくあるエラーと対処法
移行作業中に遭遇しやすいエラーメッセージとその解決策を一覧化しました。まずはここで原因を把握し、適切な手順で対処してください。
| エラーメッセージ | 主な原因 | 推奨対処法 |
|---|---|---|
error: failed to parse tauri.conf.json |
旧形式キーが残っている（例：allowlist） |
tauri migrate --force 後、手動で permissions に置換。 |
cannot find crate 'tauri' in the registry |
Rust ツールチェーンが古い、または Cargo.lock が破損 |
rustup update stable → cargo clean && cargo update |
linker "cc" not found (Linux) |
必要な C コンパイラが未インストール | sudo apt install build-essential clang（Ubuntu 系） |
The command "tauri migrate" exited with code 1 と同時に cargo metadata failed |
プロジェクト依存が v2 非対応 | npm i @tauri-apps/api@^2.0.0 にアップデートし、package.json のバージョン範囲を修正 |
Failed to notarize the macOS bundle |
Apple Developer 資格情報が CI に設定されていない | GitHub Secrets に APPLE_ID, APP_SPECIFIC_PASSWORD, TEAM_ID を追加し、workflow で環境変数として渡す |
dialog.openFile: unknown method |
API 名が変更された（v1 の open → v2 の openFile） |
コードを新シグネチャに書き換える（上記「API 変更」参照） |
共通デバッグ手順
- 詳細ログ取得：
tauri migrate -vvまたはcargo build -vv。 - キャッシュクリア：CI 環境で古いビルドが残っている場合、
cargo clean && npm cache clean --forceを実行。 - 依存更新：
cargo updateとnpm ci（またはnpm install) でロックファイルを最新化。
詳細なエラーメッセージと対処例は公式 GitHub Issues でも随時更新されています。https://github.com/tauri-apps/tauri/issues
まとめと次のアクション
Tauri 2.0 の安定版へ移行するには、環境整備 → tauri migrate 実行 → 手動設定・API 修正 → OS 別ビルド → CI/CD 自動化 という流れを順守すれば、ほぼ自動で完了します。以下にチェックリスト形式で要点を再掲し、移行後の作業指針を示します。
移行前チェックリスト
- [ ] Node ≥ 18.0、npm ≥ 9.0 がインストール済みか
node -v && npm -vで確認 - [ ] Rust stable 1.78+ と Cargo 1.78+ が利用可能か
rustc --version && cargo -Vで確認 - [ ] Tauri CLI 2.12.0 をプロジェクトローカル（devDependency）にインストール、または npx で実行できる状態にする
移行作業フロー
- dry‑run：
npx @tauri-apps/cli migrate --dry-run -vvで差分を把握 - force 実行：問題がなければ
--forceを付与して本番移行 - 設定ファイル確認：
allowlist → permissions,security.cspのオブジェクト化、macOS bundle identifier の追加等を手作業でチェック - API 書き換え：Window, Dialog など主要 API を v2 仕様に更新
ビルドとテスト
- 各 OS の必須ツールチェーン（VS Build Tools / Xcode CLI / libwebkit2gtk）を事前にインストール
npm ci && npm run build && tauri buildでローカルビルドを検証- CI/CD（GitHub Actions / GitLab CI）へ dry‑run → force migrate → build のパイプラインを組み込み、成果物をアーティファクトとして保存
移行後のメンテナンス
- 定期的に
npm outdatedとcargo outdatedを走らせ、依存が古くなったら minor/patch アップデート を実施 - 新機能や API 変更は公式リリースノート（https://github.com/tauri-apps/tauri/releases）で随時チェック
今すぐできること
| 手順 | コマンド例 |
|---|---|
| 環境バージョン確認 | node -v && npm -v && rustc --version && cargo -V |
| CLI をローカルにインストール | npm i -D @tauri-apps/cli@2.12.0 |
| dry‑run で変換差分確認 | npx @tauri-apps/cli migrate --dry-run |
| 本番移行とビルド | npx @tauri-apps/cli migrate --force && npm ci && npm run build && npx @tauri-apps/cli build |
以上の手順を踏めば、Tauri 2.0 の安定版へ安全に移行でき、今後の開発・デプロイがスムーズになります。公式ドキュメントとリリースノートは常に最新情報の唯一のソース ですので、疑問点や新機能については必ず参照してください。
本ガイドの内容は執筆時点（2026‑06）の最新版に基づいています。ツールやバージョンが更新された場合は、公式サイトを確認の上、適宜情報を更新してください。
スポンサードリンク