Capacitor 9 は以下の場所で利用可能です next dist-tag で提供されており、一般提供 (GA) に向けて進んでいます。アルファ版がリリースされた日にアプリをアップグレードする必要はありませんが、 公式 Capacitor 9 アップデートガイド と プラグイン更新ガイド ツールチェーンの最低要件と、早めに対処する価値のある API の削除項目はすでに明記しています。
この記事は 準備 チェックリストです:Capacitor 8(またはブランチ上)でできる作業を済ませておくことで、最終的な bunx cap migrate 移行作業が苦痛ではなく退屈なものになります。切り替える準備ができたら、上記でリンクされている Ionic ガイドに従って一つずつ進めてください。
ツールチェーンとプラットフォームの最低要件(アプリ)
CI、ローカルマシン、ストアのパイプラインは、以下の最低要件に合わせて計画してください:
| 項目 | Capacitor 9 の要件 |
|---|---|
| Node.js | 24+ (最新の LTS を推奨。npm 11 は Node 24 を同梱しています) |
| iOSプロファイリング | 27+ |
| iOS デプロイメントターゲット | 16.0+ |
| デバッグ | 2026.1.1+ |
| Android Gradle Plugin(AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
iOS でまだ Capacitor 8.4 以前を使っている場合は、次も必要です: UIScene ライフサイクル Cap 9 より前の Capacitor 8.5 アップデートでの対応が必要です。Xcode 27 がこれを前提としているためです。すでに 8.5 を利用しているアプリは、この追加ステップを省略できます。
iOS では、Swift 6(Xcode 27)は以下を拒否します: @UIApplicationMainアップグレードする際は、これを以下に置き換えてください: @main における AppDelegate.swift 公式ガイドに記載のとおりです。
アプリ同期時のCordova(プラグイン準備ステップではない)
Capacitor 9では、Cordova互換レイヤーは アプリに組み込まれるのは、 cap sync インストールされた Cordova プラグインを検出した場合のみです。Android では存在しない場合、余分な Gradle モジュールを削除し、iOS では CapacitorCordova を Podfile に追加したり Package.swift が存在しない場合に追加したりすることをやめます。
これはアップグレード後の アプリレベル 動作変更です。Cap 8 を使用している間は、テンプレートから Cordova を事前に削除する必要はありません。ただし、 カスタムネイティブ code (自社製またはフォークしたプラグイン)が、プロジェクトに実際の Cordova プラグインがない状態で Cordova シンボルをインポートしていないか監査してください。オプションの Cordova 配線が適用されると、これらの参照は失敗します。
Android: gradle.properties および AGP 9 のデフォルト
AGP アップグレードアシスタントは、明示的な gradle.properties フラグを書き込むことが多く、これによりビルドは AGP 8 の動作を維持します。Capacitor 9 アプリでは これらのエントリを削除し、 引き継ぐべきではありません。多くは AGP 10 に向けて非推奨となり、一部は Cap 9 のビルドを壊します(例えば android.builtInKotlin=false は AGP 9 にバンドルされている Kotlin サポートを無効にし、 android.sdk.defaultTargetSdkToCompileSdkIfUnset=false は AGP が推論する targetSdkVersion).
移行時に、以下の変更も想定してください:
- バージョンアップ
variables.gradle最低要件(compile/target SDK 37、minSdkVersion26、更新された AndroidX バージョン — 公式ドキュメントを参照)。 - 明示的な指定を削除
targetSdkVersionアプリからbuild.gradleAGP 9が以下から推論できるようにcompileSdkVersion. - 宣言する
variables.gradleの先頭にあるシンボルapp/build.gradle(Gradle 9.6ではルートプロジェクトからの暗黙的なルックアップが非推奨になります)。 - デフォルトのProGuardファイル名を変更し、移行
core-ktxまでandroidx.core:core1.19.0以降、スタンドアロンのKotlin Gradle pluginの使用をやめ、削除するjcenter().
差分(diff hunks)は次の 9.0へのアップデート Androidセクションで確認し、Capacitor のバージョンを上げる前に、ブランチ上で同様のクリーンアップを適用してください。
CLI: cap run --url
Capacitor 9では、live-reloadのhost/port/httpsフラグが1つの --url 引数に統合されました。以前は:
bunx cap run android -l --host 192.168.1.181 --port 5173
開発サーバーが出力するURLを渡してください:
bunx cap run android --url http://192.168.1.181:5173/
アップグレード後にこれまでの操作が新しいCLIと衝突しないよう、今すぐスクリプトとREADMEのスニペットを更新しておきましょう。
公式プラグイン: Push と Splash のハマりどころ
本番アプリでよく見られるユーザー向けの変更が2つあります:
プッシュ通知 (iOS): 非推奨の alert presentationオプションが削除されました。代わりに banner および/または list をpresentation optionsで使用してください。
スプラッシュスクリーン (Android): デフォルト launchFadeOutDuration からの変更点 200 ms から 0 へ。フェードで初回描画のちらつきを隠していた場合、 launchFadeOutDuration: 200 を capacitor.config で明示的に設定してください。起動 UI を調整するまで。
のプラグインセクションをスキャンし、 9.0 アップデートガイド で、使用している公式プラグインに関連する AndroidX および Google Play Services のバージョンアップを確認してください。
プラグインのメンテナー向け: Cap 8 を壊さずに Cap 8 で準備する
が Capacitor 8 で使用される Capacitor プラグインを配布している場合 と Cap 9 対応の code を求める場合は、以下に注目してください API の非推奨と削除Cap-9 固有のパッケージング変更ではありません。
Cap 8 がサポートされている間に安全に実行できること:
- 置換する
@NativePluginを使用して@CapacitorPluginレガシーな permission / activity-result API を以下に移行します@PermissionCallback/@ActivityCallbackパターン( プラグイン 9.0 ガイド の表を参照)。 - 削除
PluginCall.hasOption,Plugin.getConfigValue、旧CapConfigコンストラクタとゲッター,PluginCall.save()/isSaved()、および「code の破壊的変更」に記載されている他の Java 削除項目。 - iOS では、
CAPBridge互換性クラスや非推奨のCAPBridgeProtocolヘルパーの使用を止め、ApplicationDelegateProxy、型付きのPluginCallアクセサと、マイグレーション表にあるブリッジプロパティを使用してください。 - 実行
bunx @capacitor/plugin-migration-v8-to-v9@latestブランチを作成し、Cap 9 のメジャーバージョンを公開するまで、Cap 8 のピア依存関係に対してコンパイルできる API の編集のみを保持してください。
削除しないでください Cordova プラグインの Package.swift まだ Capacitor 8 をサポートしている間は、 プラグインが SPM ベースの場合、Cap 8 のプロジェクトはその依存関係を前提とします。早すぎる削除は、まだ 8 を使っている利用者の動作を壊します。次のように扱ってください。 Cordova をオプション化 / 無条件の依存関係を削除 Cordova 製品 として Capacitor 9 専用の Cap 8 のサポート終了後、プラグインガイドに記載のとおり、Cap 8 ラインでの準備作業ではなく、リリースライン(または Cap 9+ と明示的に記載された semver メジャー)として扱ってください。
同じ経験則が、バンプにも当てはまります。 capacitor-swift-pm まで 9.0.0-alpha.x における Package.swift: それは Cap 9 のメジャーに入れるべきで、Cap 8 互換リリースに入れるべきではありません。
Capgo Live Updates と Cap 9 のストア用ネイティブビルド
Capgo は Webバンドル のアップデートを OTA で配信します。ネイティブシェルは引き続き App Store と Google Play から提供されます。アプリを Capacitor 9 に移行する際は:
- デプロイ 少なくとも 1 つのストア向けビルドを Capacitor 9 のネイティブプロジェクト(iOS と Android)に対してコンパイルしてください。そのバイナリが、Capgo チャンネルが対象とするネイティブベースラインになります。
- そのビルドがユーザーの手元に届いてから初めて、Cap 9 の WebView とプラグインの挙動に対してテスト済みの OTA bundle を利用してください。
- 本番チャンネルを
metadata戦略に設定し、対応する Cap 9 bundle を各チャンネルに upload するには--auto-min-update-version意図的にネイティブベースラインを upload する場合は、 省略してください--fail-on-incompatible(ネイティブパッケージは変更される想定です)。維持してください--fail-on-incompatibleと--auto-min-update-versionその後の日常的なOTA uploadについては、次を参照 Native + OTAチャンネルのワークフロー. - チャンネルとsemverのルールを揃えて、古いnative shellのままのデバイスにCap 9のAPIを前提としたbundleをpushしないようにしてください。
以下を使用する場合は、 Capgo のビルド または独自のCIでエージェントを更新 の前に pipelineがユーザーのインストール内容と一致するよう、Cap 9のストアリリースに合わせて更新します: macOS runnerにはNode 24以上と Xcode 27以上が必要です; Linux ランナーには Node 24 以上と、以下に整合した Android ツールチェーンが必要です AGP 9.2.1 / Gradle 9.5.1 (Xcode は macOS のみ対応)
推奨される作業手順
- インストール済みのツールをアップグレード CI ホストと開発マシン上のツール(Node、Xcode、Android Studio、JDK)を上記の最低バージョンに更新します。 以下はしないでください: Cap 8 アプリの AGP 依存関係、Gradle ラッパー、その他の Android プロジェクトファイルを Cap 9 の値に更新するまで
bunx cap migrate— これらのプロジェクト変更は移行ステップに属します。 - 非推奨のネイティブ API を修正 アプリの code とプラグイン(特にカスタム
AppDelegateURL 処理と Android ブリッジの使用箇所)を修正します。 - Android Gradle をクリーン ファイルとスクリプト (
gradle.properties、ProGuard のデフォルト設定、--url開発スクリプト内)。 - Cordova の アプリレベルでの使用を監査してください。Cap 9 専用リリースが出るまで、プラグインの SPM Cordova プロダクトは変更しないでください。
- Cap 9 が GA になった場合(または
nextを受け入れた場合)、bun add -d @capacitor/cli@next(または@latestリリース後に実行し、bunx cap migrateを実行して 9.0へのアップデート. - Cap 9 のネイティブビルドを公開する ストアに公開し、対応するチャネルで Capgo の OTA ロールアウトを再開または拡大します。
Capacitor 9 の主なテーマは「非推奨機能の解消と、最新の Android および Apple ツールチェーンへの整合」です。Cap 8 でこれらの作業を済ませておくことで、アップグレード時の差分を最小限に保ち、現在も 8.x をリリースしているチームとのプラグイン互換性を維持できます。