capacitor-app-upgrades

Capacitor アプリのアップグレード

Capacitor アプリプロジェクトを新しいメジャーバージョン（4→5、5→6、6→7、または7→8）にアップグレードします。

前提条件

対象バージョン	Node.js	Xcode	Android Studio
5	16+	14.1+	Flamingo 2022.2.1+ (Java 17)
6	18+	15.0+	Hedgehog 2023.1.1+
7	20+	16.0+	Ladybug 2024.2.1+ (Java 21)
8	22+	26.0+	Otter 2025.2.1+

手順

ステップ 1：現在のバージョンを検出する

package.json の dependencies または devDependencies から @capacitor/core のバージョンを読み取ります。現在のメジャーバージョンを特定します。

ユーザーに対象バージョンを尋ねます。指定がない場合は、最新のバージョン（8）をデフォルトとして使用します。

ステップ 2：アップグレードを実行する

npx cap migrate は実行しないでください。 このコマンドは対話型であり、エージェントから実行できません。対応するリファレンスファイルの手順に従って、必ず各アップグレードを手動で適用してください。

現在のバージョンから対象バージョンまでのメジャーバージョン間の各移行について、対応するアップグレードガイドを順番に適用します。

現在のバージョン → 対象バージョン	リファレンス
4 → 5	references/upgrade-v4-to-v5.md
5 → 6	references/upgrade-v5-to-v6.md
6 → 7	references/upgrade-v6-to-v7.md
7 → 8	references/upgrade-v7-to-v8.md

複数バージョンをまたぐ場合（例：5 → 8）は、各アップグレードを次の順に適用します。

1. references/upgrade-v5-to-v6.md を読み、適用します
2. npx cap sync を実行し、両方のプラットフォームでビルドして検証します
3. references/upgrade-v6-to-v7.md を読み、適用します
4. npx cap sync を実行し、両方のプラットフォームでビルドして検証します
5. references/upgrade-v7-to-v8.md を読み、適用します
6. npx cap sync を実行し、両方のプラットフォームでビルドして検証します

中間バージョンをスキップしないでください。

ステップ 3：最終確認

すべてのアップグレード手順を完了した後：

npx cap sync
npx cap run android
npx cap run ios

エラー処理

• アップグレード後に Android のビルドが失敗した場合は、Android Studio で Tools > AGP Upgrade Assistant を実行します。
• iOS のビルドが失敗した場合は、デプロイメントターゲットがリファレンスファイルに記載された対象バージョンの要件と一致していることを確認します。
• Gradle プロパティの構文に関する警告が表示された場合（v8+）、すべての .gradle ファイルで = を使わないプロパティの代入を検索し、修正します。
• 複数バージョンにまたがるアップグレードの途中で失敗した場合は、次に進む前に現在のバージョンの手順を修正します。

関連スキル

• capacitor-app-development — アップグレード完了後の一般的な Capacitor 開発のトピック、トラブルシューティング、ベストプラクティスについては、こちらを参照してください。
• capacitor-plugin-upgrades — プロジェクトにアップグレードが必要な Capacitor プラグインが含まれている場合は、アプリのアップグレード後にこのスキルを使用します。
• capacitor-plugins — アプリのアップグレード後にプラグインをインストールまたは再設定する場合に使用します。
• ionic-app-upgrades — プロジェクトで Ionic Framework UI ライブラリを使用している場合は、Capacitor と合わせて Ionic のバージョンもアップグレードが必要になることがあります。