capacitor-plugin-upgrade-v8-to-v9

Capacitor Plugin Upgrade v8 to v9

Capacitor 9 はプレリリースです（2026 年 10 月時点で、next dist-tag、9.0.0-alpha.x）。以下の依存関係の範囲はプレリリースを対象としています。9.0.0 GA のリリース後は、^9.0.0 / from: "9.0.0" を使用してください。プレリリース版のコアのみをサポートする安定版プラグインを公開する前に、ユーザーに伝えてください。npm の next タグを付けて公開するのが一般的です。

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

使用するタイミング

次の場合に使用します：

• プラグインリポジトリの peerDependencies["@capacitor/core"] が ^8 または >=8 で、ユーザーが Capacitor 9 のサポートを希望している
• 削除された API（CAPBridge、@NativePlugin、saveCall、getWebView()、isSimulator()）が原因で、プラグインを Capacitor 9 向けにコンパイルできない
• AGP 9 / Gradle 9 で、プラグインの android/build.gradle のビルドに失敗する（jcenter()、kotlin-android、proguard-android.txt、名前空間の衝突）
• Cordova プラグインを使用していないアプリで、プラグインの Cordova SPM プロダクトまたは com.getcapacitor.cordova のインポートが原因でビルドに失敗する

使用しないでください：

• アプリのプロジェクト → capacitor-app-upgrade-v8-to-v9
• プラグインがまだ 7 以前 → capacitor-plugin-upgrades（メジャーバージョンを順に適用）
• CocoaPods のみのプラグインに SPM を追加する → capacitor-plugin-spm-support
• プラグインが 8.5 の UIScene ライフサイクルに対応しているかだけを確認する → capacitor-uiscene-migration（references/plugin-audit.md）

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

!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=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}out.push('Package.swift='+fs.existsSync('Package.swift'));out.push('podspec='+fs.readdirSync('.').filter(f=>f.endsWith('.podspec')).join(','));console.log(out.join('\n'))"

!find . -maxdepth 3 \( -path './example-app' -o -path './example' -o -path './ios' -o -path './android' \) -not -path './node_modules/*'

手順

1. 確認します。 スナップショット、android/build.gradle、android/gradle.properties、.podspec、Package.swift を読み、ネイティブソース（android/src/main、ios/Sources または ios/Plugin）を一覧表示します。サンプルアプリのパスも確認します。ツリーがクリーンであることを確認します（git status）。
2. プラグインのルートからマイグレーターを実行します。

   npx @capacitor/plugin-migration-v8-to-v9@latest
   

   差分を確認します（git diff）。ほとんどのファイル編集が対象ですが、コード内の API 削除は対象外です。
3. package.json の依存関係：
   • devDependencies：@capacitor/cli、@capacitor/core、@capacitor/android、@capacitor/ios -> next。
   • peerDependencies["@capacitor/core"]：>=9.0.0-alpha.6（現在のプレリリースは npm view @capacitor/core dist-tags で確認してください）。リリースで 8 も引き続きサポートするか確認します。iOS 16 / AGP 9 のビルド変更には後方互換性がないため、ほとんどのプラグインは 8 のサポートを終了します。
4. references/build-files.md に従ってビルドファイル（gradle.properties、build.gradle、podspec、Package.swift）を更新します。podspec と Package.swift の両方を維持してください。CocoaPods と SPM のどちらを使うアプリでもプラグインを利用するためです。
5. コード API の削除。 grep で検索し、references/android-api-removals.md と references/ios-api-removals.md に従って該当箇所をそれぞれ修正します。非推奨の呼び出し経路を #if やリフレクションの背後に残さないでください。
6. Cordova のオプション対応。 Package.swift から無条件の .product(name: "Cordova", ...) を削除します。プラグインのネイティブコードが Cordova 互換クラス（com.getcapacitor.cordova.*、CDV*）をインポートしている場合、Cordova プラグインのないアプリでは動作しません。ユーザーに置き換え方法を確認してください。
7. UIScene のライフサイクル。 Capacitor 9 のアプリはすべてシーンベースです。AppDelegate メソッドへの依存、tmpWindow、keyWindow による表示、applicationState を iOS コードで監査します（capacitor-uiscene-migration -> references/plugin-audit.md）。最小バージョンが 9 になったため、.capacitorScene* 通知と SceneDelegateProxy を安全に使用できます。
8. サンプルアプリとドキュメント。 capacitor-app-upgrade-v8-to-v9 を使ってサンプルアプリをアップグレードします。README のインストール方法／互換性テーブルを更新します（Capacitor 9、iOS 16、minSdk 26）。
9. references/verification.md に従って検証します。プラグインのメジャーバージョンを上げます。

注意点

• AGP 9 では android.uniquePackageNames=true がデフォルトです。スキャフォールドのデフォルト名前空間（com.mycompany.plugins.example）や、アップストリームの名前空間をそのまま使っているフォークでは、利用側アプリのビルドが失敗します。一意な値にしてください。
• ライブラリモジュールの targetSdkVersion は実行時に影響しません。引き上げるのではなく削除してください。
• CapacitorUrlRequest.setRequestHeaders([String: Any]) は値を設定し、追加するものではありません。同じヘッダーキーを繰り返すと、後の値で上書きされます。
• Package.swift は capacitor-swift-pm の from: "9.0.0-alpha.6" 以降を参照する必要があります（それ以前のアルファ版では Cordova のオプション対応に関するクラッシュが発生していました）。最新のアルファ版を使ってください。
• googleMapsUtilsVersion 5.0.0 には、アップストリームの API 破壊的変更が含まれています。
• プラグインのルートで npx cap sync を実行しても役に立ちません。同期はサンプルアプリ内で行ってください。

エラー処理

エラー	修正方法
cannot find symbol ... class NativePlugin	@CapacitorPlugin(name = ..., permissions = ...)
cannot find symbol ... method saveCall(PluginCall)	call.setKeepAlive(true) または bridge.saveCall(call)
cannot find symbol ... method pluginRequestPermission(...)	requestPermissionForAlias(alias, call, "callbackName") + @PermissionCallback
Cannot find 'CAPBridge' in scope	ApplicationDelegateProxy.shared / Notification.Name.capacitorStatusBarTapped
Value of type 'CAPBridgeProtocol' has no member 'getWebView'	bridge?.webView（ほかのゲッターも同様に、プロパティを使用します）
AGP 9 で Kotlin プラグインの重複または競合エラーが発生する	単独の Kotlin プラグインと stdlib を削除します
利用側アプリで名前空間の競合／パッケージの重複が発生する	android/build.gradle の namespace を一意にします
利用側アプリで Cordova に関する SPM の解決またはリンクエラーが発生する	Cordova のプロダクト依存関係を削除します

参考資料

対象の内容に関わる場合にのみ、参考資料を読み込んでください。

ファイル	読み込むタイミング
references/build-files.md	gradle.properties、build.gradle、podspec、Package.swift、ラッパーを編集するとき
references/android-api-removals.md	Java/Kotlin のコンパイルエラー、または grep の該当箇所があるとき
references/ios-api-removals.md	Swift/ObjC のコンパイルエラー、または grep の該当箇所があるとき
references/verification.md	編集後：grep、ビルド、サンプルアプリの確認、公開

関連スキル：capacitor-plugin-upgrades、capacitor-app-upgrade-v8-to-v9、capacitor-uiscene-migration、capacitor-plugin-spm-support。