capacitor-app-upgrade-v8-to-v9

Capacitor App Upgrade v8 to v9

Capacitor 9 はプレリリース版です（2026 年 10 月時点で next dist-tag、9.0.0-alpha.x）。インストールには @next を使用してください。9.0.0 が GA になったら、@latest / ^9.0.0 に切り替えてください。本番アプリをアップグレードする前に、GA 版ではないことをユーザーに伝え、ブランチで作業してください。

正規の情報源：https://capacitorjs.com/docs/updating/9-0

使用する場合

次の場合に使用してください：

• アプリが @capacitor/core 8.x を使用しており、ユーザーが Capacitor 9 を希望している
• Capacitor 8 アプリを Xcode 27 / Swift 6、AGP 9、または Gradle 9 に移行した後にビルドエラーが発生する
• npx cap run -l --host ... が動作しなくなった（--url に置き換えられました）
• iOS で Push 通知の presentationOptions: ['alert'] によるバナーが表示されなくなった
• Cordova プラグインを使用していないアプリで、アップグレード後に CapacitorCordova / com.getcapacitor.cordova 参照に関するエラーが発生する

使用しない場合：

• アプリがまだ 7 以前の場合 → capacitor-app-upgrades（メジャーバージョンを順に移行してください）
• 8.4 → 8.5 の UIScene 移行のみの場合 → capacitor-uiscene-migration
• プラグインライブラリのリポジトリの場合 → capacitor-plugin-upgrade-v8-to-v9
• CocoaPods から SPM への移行の場合 → cocoapods-to-spm（推奨されますが、別の手順です）

ライブプロジェクトのスナップショット

!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)}}out.push('node='+process.version);const p='ios/App/App/';out.push('ios.SceneDelegate='+fs.existsSync(p+'SceneDelegate.swift'));out.push('ios.Podfile='+fs.existsSync('ios/App/Podfile'));console.log(out.sort().join('\n'))"

手順

1. 事前確認（いずれかが失敗したら中止して報告してください）

node --version                     # must be >= 24
xcodebuild -version                # must be Xcode 27+
java -version                      # use the JDK bundled with Android Studio 2026.1.1+
grep -c UIApplicationSceneManifest ios/App/App/Info.plist
git status --short                 # clean tree, so the migration diff is reviewable

• Node < 24 または Xcode < 27 の場合：先にツールをアップグレードするようユーザーに依頼してください。
• シーンマニフェストまたは SceneDelegate.swift がない場合：アプリは UIScene に移行していません。まず 8.5 で capacitor-uiscene-migration スキルを実行し、検証してから、ここに戻ってください。両方を同時に行うと、ディープリンクが動作しなくなった原因を特定しにくくなります。
• 移行前にネイティブのカスタマイズを確認してください：カスタムの AppDelegate / SceneDelegate コード、カスタムの CAPBridgeViewController サブクラス、ios/App/App または android/app/src 内のローカルプラグイン、variables.gradle 内の追加変数、Cordova プラグイン（npx cap ls）。

2. パッケージと自動移行

npm i -D @capacitor/cli@next
npx cap migrate

cap migrate は依存関係とテンプレートに準じたネイティブファイルを更新し、対応できなかった項目を表示します。モノレポ向けには作られていないため、モノレポは手動で移行してください。その後、ほかの @capacitor/* パッケージもすべて @next に更新し（公式プラグインも 9.0.0 です）、Capgo およびサードパーティ製プラグインに Capacitor 9 対応版があるか確認してください（npm view <pkg> peerDependencies）。

3. 手動チェックリスト（migrate が成功と報告した場合も、各項目を確認してください）

• iOS → references/ios.md：Xcode 27、pbxproj + Podfile の iOS 16.0、@main、アプリコード内の削除された CAPBridge / ブリッジ API、SPM の推奨事項。
• Android → references/android.md：gradle.properties のクリーンアップ、variables.gradle の値、targetSdkVersion の削除、proguard-android-optimize.txt、明示的な rootProject.ext 定義、core-ktx、Kotlin プラグインの削除、jcenter()、AGP 9.2.1、Gradle 9.5.1、google-services 4.5.0。
• プラグイン、CLI、設定 → references/plugins-and-cli.md：公式プラグインの変数更新、Push 通知の alert、スプラッシュ画面の launchFadeOutDuration、cap run --url、Cordova ランタイムがオプションになったこと。

4. 同期、ビルド、検証

npx cap sync を実行し、その後 references/verification.md に記載されたすべての項目を実行してください：残存シンボルの grep、両方のネイティブビルド、デバイスでの確認。結果はプラットフォームごとに報告してください。

注意点

• gradle.properties に android.builtInKotlin=false または android.sdk.defaultTargetSdkToCompileSdkIfUnset=false を残すと（AGP Upgrade Assistant がこれらを書き込みます）、ビルドが失敗します。AGP 8 の互換性ブロック全体を削除してください。
• proguard-android.txt は、minifyEnabled false であっても設定時に失敗します。
• AGP 9 組み込みの Kotlin と並べて apply plugin: 'kotlin-android' を残すと、ローカルのプラグインモジュール内も含め、プラグイン重複エラーで失敗します。
• Cordova プラグインが一つもないアプリでは、CapacitorCordova / capacitor-cordova-android が含まれなくなりました。これらのシンボルをインポートするネイティブコードはコンパイルできなくなります。強制的に含めるフラグはありません。
• UIScene 以前の AppDelegate コード（CAPBridge.handleOpenUrl、application(_:open:) のカスタムロジック）はコンパイルに失敗するうえ、呼び出されることもありません。SceneDelegate に移してください。
• CocoaPods Trunk は 2026 年 12 月 2 日に読み取り専用になる予定です。アップグレードが正常に完了した後に cocoapods-to-spm を提案してください。

エラー処理

エラー	修正方法
'@UIApplicationMain' is deprecated（Swift 6 モードでエラー）	@main に置き換えます
Cannot find 'CAPBridge' in scope	ApplicationDelegateProxy.shared API（references/ios.md）を使用します
Could not find method jcenter()	ローカルプラグインも含め、すべての build.gradle で mavenCentral() に置き換えます
proguard-android.txt に関する設定失敗	proguard-android-optimize.txt を使用します
Kotlin プラグインが適用済み／プラグイン org.jetbrains.kotlin.android の重複	kotlin-android、kotlin-gradle-plugin のクラスパス、kotlin-stdlib を削除します
クラス androidx.core.*（core-ktx）の重複	古い core-ktx を削除し、androidx.core:core:1.19.0 に依存します
Could not get unknown property 'androidxAppCompatVersion'	app/build.gradle の先頭に def x = rootProject.ext.x を追加します
ライブラリモジュール間の名前空間の競合	プラグインに残っているひな形／フォーク版の namespace を更新するか、そのプラグインについて報告します
cap run で error: unknown option '-l'	npx cap run <platform> --url http://<ip>:<port>
npm ERR! engine／Node のバージョンエラー	Node 24 以降

参考資料

トピックに関係する場合にのみ、参考資料を読み込んでください。

ファイル	読み込むタイミング
references/ios.md	iOS の手順または iOS ビルドエラーがある場合
references/android.md	Android／Gradle の手順またはビルドエラーがある場合
references/plugins-and-cli.md	公式プラグインの動作変更、ライブリロード、Cordova プラグインについて確認する場合
references/verification.md	同期後：grep、ビルド、デバイスのチェックリスト

関連スキル：capacitor-uiscene-migration、capacitor-app-upgrades、capacitor-plugin-upgrade-v8-to-v9、cocoapods-to-spm、capacitor-push-notifications、capacitor-splash-screen。