capacitor-app-upgrade-v7-to-v8

Capacitor App Upgrade v7 to v8

Capacitor 7 アプリを Capacitor 8 に移行します（現行の安定版系列：8.5.x）。一次情報：https://capacitorjs.com/docs/updating/8-0

使用するタイミング

• 以下のスナップショットで @capacitor/core が 7.x で、ユーザーが 8.x を希望している場合。
• 8 に更新した後、Android のステータスバー／ナビゲーションバーの下にコンテンツが表示される（エッジツーエッジ）、bridge_layout_main が見つからない、Gradle の「space-assignment syntax」に関する非推奨警告、Kotlin 2 の kotlinOptions エラー、または Geolocation のタイムアウトが発生した場合。
• ユーザーが 7 から 8 への正確なチェックリストを求めている場合。

使用しないでください：

• アプリが 6.x の場合 → 最初に capacitor-app-upgrade-v6-to-v7 を使用してください。複数段階の移行計画には capacitor-app-upgrades を使用してください。
• アプリがすでに 8.x の場合 → capacitor-uiscene-migration（8.5 のシーンライフサイクル）を使用し、その後 capacitor-app-upgrade-v8-to-v9 を使用してください。
• プラグインライブラリのアップグレードには → capacitor-plugin-upgrade-v7-to-v8 を使用してください。
• 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'))"

参考資料

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

ファイル	読み込むタイミング
references/android.md	variables.gradle、Gradle の構文、ラッパー、マニフェスト、Kotlin、またはエッジツーエッジを編集する場合
references/plugins.md	アプリで公式の @capacitor/* プラグイン（Geolocation、Screen Orientation、Barcode Scanner、Status Bar など）を使用している場合

事前確認

ツール	Capacitor 8 の最小要件
Node.js	22 以上（最新の LTS を推奨）
Xcode	26.0 以上
iOS デプロイメントターゲット	15.0
Android Studio	Otter 2025.2.1 以上
Java（Gradle JDK）	21
AGP / Gradle	8.13.0 / 8.14.3
Android SDK	minSdk 24、compileSdk 36、targetSdk 36
Kotlin（使用する場合）	2.2.20

node -v && xcodebuild -version && java -version
git status --short
grep -rn "adjustMarginsForEdgeToEdge\|appendUserAgent" capacitor.config.*
grep -rn "bridge_layout_main" android/ src/ 2>/dev/null

手順

1. スナップショットで 7.x を確認します。ユーザーに minSdk 24 と iOS 15 により古いデバイスが対象外になることを伝えます。

2. 自動移行を実行します（latest は最新の 8.x に解決されます）。

   npm i -D @capacitor/cli@latest
   npx cap migrate            # add --noprompt in CI, --packagemanager pnpm|yarn if not npm
   

   ^8.0.0 のパッケージをインストールし、iOS のターゲット／Podfile を 15.0 に引き上げ、cap sync を実行し、configChanges に density を追加し、Gradle ラッパーと Gradle ファイルをアップグレードして、破壊的変更を書き出します。失敗として報告された手順はすべて完了させてください。最後に Migration to Capacitor <v> is complete または ... is incomplete. Check the log messages for more information. と表示されます。

3. 設定（capacitor.config.*）：

   • android.adjustMarginsForEdgeToEdge は削除されました。これを削除し、System Bars コアプラグインと CSS env(safe-area-inset-*) でインセットを処理します（references/android.md と safe-area-handling を参照）。
   • iOS の appendUserAgent は、余分なスペースを 2 つ追加しなくなりました。サーバーが以前の UA を解析する場合は、ios.appendUserAgent のみに先頭のスペースを追加してください（Android にも影響するルートキーには追加しないでください）。

4. iOS：

   • プロジェクトとすべてのターゲットで iOS Deployment Target = 15.0 を設定します（CocoaPods プロジェクトでは、Podfile に platform :ios, '15.0' を設定します）。
   • Capacitor は viewDidAppear と viewWillTransition の CAPBridgeViewController 通知を出力するようになりました。アプリ拡張機能がこれらを独自に送信していた場合は削除してください。そうしないとリスナーが二重に呼び出されます。

5. Android：references/android.md（変数、= 代入構文、AGP 8.13.0、Gradle 8.14.3、google-services 4.4.4、Kotlin 2.2.20、density）を適用します。bridge_layout_main を参照している箇所は capacitor_bridge_layout_main に名前を変更します。

6. @capacitor/* プラグインを ^8.0.0 に、コミュニティプラグインを各 v8 リリースに更新します。references/plugins.md を適用します。

7. CLI に関する注意：npx cap add ios は SPM プロジェクトを生成するようになりました。既存の CocoaPods アプリには影響しません。再追加時に Pods を維持するには、npx cap add ios --packagemanager CocoaPods を使用します。CocoaPods Trunk は読み取り専用になる予定（2026 年 12 月 2 日の見込み）のため、アップグレード後に cocoapods-to-spm を推奨してください。

8. 検証を実行します。

8.x 以降：次に必要な手順

• Xcode 27 では iOS UIScene ライフサイクルが必要です。Capacitor 8.5 でこれが採用されました（SceneDelegate、UIApplicationSceneManifest）。このアップグレード後、Xcode 27 でビルドする前にスキル capacitor-uiscene-migration を実行してください。シーンを採用すると、AppDelegate の application(_:open:options:)、continue userActivity、およびフォアグラウンド／バックグラウンドのライフサイクルコールバックは呼び出されなくなります。ディープリンクとカスタム AppDelegate コードはシーンデリゲートに移動する必要があります。
• 次に capacitor-app-upgrade-v8-to-v9 を実行します（Capacitor 9 はまだ GA ではなく、next タグで公開されています）。

検証

grep -rn "adjustMarginsForEdgeToEdge\|bundledWebRuntime" capacitor.config.*   # expect none
grep -rn "bridge_layout_main" android/app/src src/ | grep -v capacitor_bridge   # expect none
grep -rn "IPHONEOS_DEPLOYMENT_TARGET" ios/App/App.xcodeproj/project.pbxproj | sort -u   # 15.0
grep -n "gradle:8.13.0\|google-services:4.4.4" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties    # gradle-8.14.3
grep -n "SdkVersion" android/variables.gradle                                 # 24 / 36 / 36
grep -nE "^\s*(namespace|compileSdk|ignoreAssetsPattern) [^=]" android/app/build.gradle   # expect none
grep -n "configChanges" android/app/src/main/AndroidManifest.xml              # includes density
npx cap sync
cd android && ./gradlew assembleDebug --warning-mode all

Xcode 26 以降で iOS をビルドし、デバイスで実行します。Android 15 以降／16 では、コンテンツがステータスバーやナビゲーションバーの下に入り込んでいないことを確認します。

エラー処理

エラー	修正方法
Migrate can only be used on Capacitor 7, please use the CLI in Capacitor 7 to upgrade to 7 first	先に capacitor-app-upgrade-v6-to-v7 を実行します。
Capacitor 8 requires JDK 21 or higher. Some steps may fail.	Gradle JDK を 21 に設定します。
Unable to add 'density' to 'android:configChanges' in <file>. Try adding it manually	メインアクティビティの configChanges に `
gradle wrapper files were not updated	distributionUrl を gradle-8.14.3-all.zip に編集し、cd android && ./gradlew wrapper を実行します。
Unable to find "<text>" in <file>. Try updating it manually	references/android.md の差分を適用します。
Properties should be assigned using the 'propName = value' syntax（Gradle の非推奨警告）	プロパティの代入に = を追加します。
R.layout.bridge_layout_main の cannot find symbol（または AAPT の resource layout/bridge_layout_main ... not found）	capacitor_bridge_layout_main を使用します。
Kotlin：kotlinOptions／kotlin-android-extensions エラー	kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } } に移行します。synthetics を view binding に、parcelize を kotlin-parcelize に置き換えます。