capacitor-app-upgrades

Capacitor アプリのアップグレード（ルーター）

バージョンごとのスキルを各段階で使い、一度に1段階ずつ Capacitor アプリのアップグレードを計画して実行します。

使用するタイミング

次の場合にトリガーします。

• ユーザーが Capacitor アプリのアップグレードを希望しており、開始バージョンまたは目標バージョンが不明、あるいはメジャーバージョンが2つ以上離れている
• ユーザーが「最新の Capacitor」を希望している（安定版の8.5.xとプレリリース版の9のどちらにするか相談します）
• Capacitor 8.4以前のアプリで Xcode 27 のビルドに失敗する（8.5の UIScene 手順が必要です）
• npx cap migrate が途中で失敗し、現在の状態を確認する必要がある

次の場合は使用しないでください。

• プラグインライブラリのリポジトリ → capacitor-plugin-upgrades
• Cordova／PhoneGap アプリ → cordova-to-capacitor
• CocoaPods から SPM への移行のみ → cocoapods-to-spm

プロジェクトの現在のスナップショット

package.json に含まれる現在の Capacitor パッケージ： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

ネイティブ設定と Capacitor 設定のパス： !find . -maxdepth 3 \( -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './ios' -o -path './android' \)

バージョン一覧（2026年10月）

段階	スキル	段階完了後の主な要件
4 -> 5	capacitor-app-upgrade-v4-to-v5	スキルを参照
5 -> 6	capacitor-app-upgrade-v5-to-v6	スキルを参照
6 -> 7	capacitor-app-upgrade-v6-to-v7	スキルを参照
7 -> 8	capacitor-app-upgrade-v7-to-v8	Node 22、Xcode 26、iOS 15、minSdk 24、SDK 36、AGP 8.13、Gradle 8.14.3
8.x -> 8.5	capacitor-uiscene-migration	iOS UIScene ライフサイクル（SceneDelegate と scene manifest）。Xcode 27 で必須です
8.5 -> 9	capacitor-app-upgrade-v8-to-v9	Node 24、Xcode 27、iOS 16、minSdk 26、SDK 37、AGP 9.2.1、Gradle 9.5.1

Capacitor の安定版は8.5.x（latest）です。Capacitor 9 は next タグのプレリリース版（9.0.0-alpha.x）です。9.0.0 が GA になるまでは @next を指定してインストールし、その後は @latest を指定します。本番アプリをプレリリース版に移行する前に、必ず確認してください。8.5は安全に移行を止められるバージョンであり、すでに Xcode 27 でビルドできます。

手順

1. 検出します。 スナップショットから @capacitor/core を確認します（範囲指定が曖昧な場合は npm ls @capacitor/core を実行します）。8.x の場合は、UIScene が採用されているかも確認します：grep -c UIApplicationSceneManifest ios/App/App/Info.plist。
2. 目標を選びます。 ユーザーから指定がない場合は、安定版（8.5.x）かプレリリース版（9）かをユーザーと相談します。
3. 段階を計画します。 メジャーバージョンは一度に1つずつ進め、決して飛ばさないでください。8.0～8.4から9に進む場合は、まず8.5の UIScene 移行を挟みます。例：
   • 6 -> 9：6->7、7->8、8->8.5（UIScene）、8.5->9
   • 8.2 -> 9：8.2->8.5（UIScene）、8.5->9
   • scene manifest がない8.5から9へ：まず capacitor-uiscene-migration を実行します 大規模なアプリでは、各段階を TODO リストにまとめ、ユーザーに確認します。
4. 各段階で実行します。 Git の作業ツリーがクリーンであることを確認し、その段階のスキルを読み込み、目標バージョンの CLI をインストールし（npm i -D @capacitor/cli@<major>、9の場合は @next）、npx cap migrate を実行します。手動チェックリストを完了し、npx cap sync を実行してから、iOS と Android のビルドを行います。両方のビルドが成功するまで次の段階に進まないでください。失敗を二分探索で特定できるよう、各段階でのコミットを推奨します。
5. プラグインを確認します。 各段階の完了後、公式の @capacitor/* プラグインを同じメジャーバージョンにそろえ、サードパーティおよび @capgo/* プラグインの peer range を確認します（npm view <pkg> peerDependencies）。
6. 最終確認（以下を参照）の後、追加の対応として cocoapods-to-spm（CocoaPods Trunk は2026年12月2日に読み取り専用になる見込みです）と、ネイティブバージョンごとの Capgo ライブアップデート用チャンネルを案内します。

検証

npx cap doctor
npm run build && npx cap sync
cd android && ./gradlew assembleDebug && cd ..
xcodebuild -project ios/App/App.xcodeproj -scheme App -destination 'generic/platform=iOS Simulator' build   # CocoaPods: -workspace ios/App/App.xcworkspace
npx cap run ios
npx cap run android

デバイス上で、アプリの起動、pause／resume、コールドおよびウォーム状態でのディープリンク、プッシュ通知の登録、各ネイティブプラグインを1回ずつ呼び出すことを確認します。アプリが OTA アップデート（Capgo）を配信する場合、新しいネイティブバージョンには新しいネイティブビルドが必要です。v9 用にビルドされたバンドルを v8 のバイナリに送信しないでください（capgo-live-updates を参照）。

エラー処理

• cap migrate が途中で停止する場合 → そのスキルに従って、該当する移行を手動で完了してください。次のメジャーバージョンには進まないでください。
• Migrate can only be used on Capacitor 7 → インストールされている CLI がプロジェクトより新しいバージョンです。まず古い CLI に切り替えてください。
• UIScene migration: project is in a partial state → capacitor-uiscene-migration で対応できます。
• 移行後に iOS のビルドが失敗する場合 → Version Map に照らして、デプロイメントターゲットと Xcode のバージョンを確認してください。
• Android のビルドが失敗する場合 → 移行対象のスキルに照らして、AGP、Gradle ラッパー、JDK、variables.gradle を確認してください。
• サードパーティ製プラグインが移行を妨げる場合 → アップグレードするか、置き換えるか（Capgo に相当するものがあるか capacitor-plugins で確認してください）、現在の移行段階でいったん止めてください。