Capacitor 9への備え：アプリ・プラグイン開発チームが今すべきこと

Capacitor 9 は以下で利用可能です： next GA（一般公開）に向けて、現在は dist-tag で提供されています。アルファ版がリリースされた当日にアプリをアップグレードする必要はありませんが、 Capacitor 9 公式アップデートガイド と プラグインのアップデートガイド ツールチェーンの制約や、早めに対処しておくべき API の削除事項について説明します。

この記事は、 準備 チェックリストです。Capacitor 8（またはそのブランチ）で行える作業をまとめました。これにより、最終的な bunx cap migrate 移行作業を、苦痛なものではなくスムーズなものにできます。移行の準備ができたら、上記の Ionic ガイドに従って一行ずつ進めてください。

ツールチェーンとプラットフォームの制約（アプリ）

CI、ローカルマシン、ストアのパイプラインを、以下の最小要件に基づいて計画してください：

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はPodfileへの追加を CapacitorCordova 停止します。または、 Package.swift プラグインが存在しない場合に動作します。

これは、 アップグレード後の アプリレベルの挙動変更です。Cap 8を使用している間は、事前にテンプレートからCordovaを削除する必要はありません。ただし、以下の点を確認してください。 カスタムネイティブのcodeが (自作またはフォークしたプラグイン) プロジェクト内に実際のCordovaプラグインがない状態でCordovaのシンボルをインポートしていないか。これらは、Cordovaの接続がオプション化されると参照エラーになります。

Android: gradle.properties および AGP 9 のデフォルト設定

AGP Upgrade Assistant は、ビルド時に AGP 8 の挙動を維持するために、明示的な gradle.properties フラグを書き込むことがよくあります。Capacitor 9 のアプリでは、 削除すべきです。 それらのエントリを引き継ぐのではなく削除してください。多くは AGP 10 に向けて非推奨となっており、一部は Capacitor 9 のビルドを壊します（例： android.builtInKotlin=false AGP 9 に同梱されている Kotlin サポートを無効化したり、 android.sdk.defaultTargetSdkToCompileSdkIfUnset=false AGP による推論を停止させたりします）。 targetSdkVersion).

移行時には、以下の対応も必要になります：

• 更新 variables.gradle 最小バージョン（compile/target SDK 37、 minSdkVersion 26、および更新された AndroidX バージョン — 公式ドキュメントを参照）
• 明示的な指定を削除 targetSdkVersion アプリから build.gradle AGP 9が以下から推論できるように compileSdkVersion.
• 宣言する variables.gradle の先頭にあるシンボル app/build.gradle (Gradle 9.6ではルートプロジェクトからの暗黙的なルックアップが非推奨になります)。
• デフォルトのProGuardファイル名を変更し、移行 core-ktx まで androidx.core:core 1.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 update guide で確認してください。 使用中の公式プラグインに関連する AndroidX や Google Play Services のバージョンアップ情報が記載されています。

プラグイン開発者の皆様へ：Cap 8 の動作を壊さずに Cap 9 への準備を進めてください。

Capacitor 8 で使用される Capacitor プラグインをリリースしている場合： と Cap 9に対応したcodeを目指すなら、以下に注力してください： 非推奨となったAPIの削除Cap 9固有のパッケージング変更ではありません。

Cap 8がサポートされている間に進めておくべき事項：

• 置き換え @NativePlugin を使用して @CapacitorPlugin および、レガシーな権限/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 の peer dependencies に対してコンパイルが通る API の編集内容のみを保持してください。

以下の項目は削除しないでください： Cordova プラグインの SPM プロダクト Package.swift Capacitor 8 のサポートを継続している間は、 プラグインが SPM ベースの場合、Cap 8 のプロジェクトはその依存関係を必要とします。早めに削除すると、まだ 8 を使用しているユーザーに影響が出ます。そのため、 Cordova をオプションにするか、無条件の Cordova 製品 を Capacitor 9 専用の リリースライン（または Cap 9+ と明記された semver メジャーバージョン）として扱ってください。これは Cap 8 のサポートを終了した後に、プラグインガイドに従って行うべきことであり、Cap 8 のラインで行う準備作業ではありません。

同様のルールが、バージョンアップにも適用されます。 capacitor-swift-pm まで 9.0.0-alpha.x における Package.swift: これは Cap 9 のメジャーリリースで行うべきであり、Cap 8 と互換性のあるリリースで行うべきではありません。

Capgo live updates とネイティブな Cap 9 ストアビルド

Capgo は web bundle のアップデートを OTA で配信します。ネイティブシェルは引き続き App Store と Google Play から提供されます。アプリを Capacitor 9 に移行する際は：

1. デプロイ 少なくとも 1 つのストア向けビルドを Capacitor 9 のネイティブプロジェクト（iOS と Android）に対してコンパイルしてください。そのバイナリが、Capgo チャンネルが対象とするネイティブベースラインになります。
2. そのビルドがユーザーの手元に届いてから初めて、Cap 9 の WebView とプラグインの挙動に対してテスト済みの OTA bundle を利用してください。
3. 本番チャンネルを metadata 戦略に設定し、対応する Cap 9 bundle を各チャンネルに upload するには --auto-min-update-version意図的にネイティブベースラインを upload する場合は、 省略してください --fail-on-incompatible （ネイティブパッケージは変更される想定です）。維持してください --fail-on-incompatible と --auto-min-update-version その後の日常的なOTA uploadについて。詳細は Native + OTA チャンネルのワークフロー.
4. チャンネルとsemverのルールを同期させ、古いNative shellが動作しているデバイスに、Cap 9のAPIを前提としたbundleを誤ってpushしないようにしてください。

もし Capgo のビルド や独自のCIを使用している場合は、エージェントを更新して の前に のCap 9ストアリリースと同期させ、pipelineをユーザーがインストールするものと一致させてください： macOS のrunnerにはNode 24以上と Xcode 27以上が必要です; Linux のランナーには Node 24+ と、以下のバージョンに合わせた Android ツールが必要です： AGP 9.2.1 / Gradle 9.5.1 (Xcode は macOS のみ)。

推奨される作業手順

1. インストール済みツールのアップグレード CI ホストおよび開発環境のツール（Node, Xcode, Android Studio, JDK）を上記のバージョンへ更新します。 注意： Cap 8 アプリの AGP 依存関係、Gradle wrapper、またはその他の Android プロジェクトファイルを Cap 9 の値に更新しないでください。理由は、 bunx cap migrate — それらのプロジェクト変更は移行ステップで行うべきものだからです。
2. 非推奨になった native API の修正 アプリ code およびプラグイン（特にカスタム AppDelegate URLのハンドリングとAndroidブリッジの使用方法）。
3. Android Gradleのクリーンアップ ファイルとスクリプト（gradle.properties、ProGuardのデフォルト設定、 --url 開発用スクリプト内）。
4. Cordovaの使用状況を アプリレベルで監査してください。Cap 9専用リリースが出るまでは、プラグインのSPM Cordova製品を変更しないでください。
5. Cap 9がGA（一般公開）になった際（または、 next）、 bun add -d @capacitor/cli@next を実行（ @latest 、リリース後）、その後 bunx cap migrate、および 9.0へのアップデート.
6. Cap 9のNative Buildをリリースし、 ストアへ公開した後、対応するチャネルでCapgoのOTAロールアウトを再開または拡大しましょう。

Capacitor 9の主な目的は「非推奨機能の整理と、最新のAndroidおよびAppleツールチェーンへの適合」です。Cap 8の段階でこれらの対応を進めておくことで、アップグレード時の差分を最小限に抑え、現在も8.xをリリースしているチームのプラグインとの互換性も維持できます。