capacitor-app-upgrade-v6-to-v7

Capacitor App Upgrade v6 から v7 へ

Capacitor 6 のアプリを Capacitor 7 に移行します。正確な情報源：https://capacitorjs.com/docs/updating/7-0

使用する場合

• 以下のスナップショットで @capacitor/core が 6.x で、ユーザーが 7.x を希望している場合。
• 7 への更新後に、JDK 21／AGP 8.7 のエラー、iOS デプロイメントターゲット 13 のエラー、または削除された非推奨プラグイン型に関する TypeScript エラーが原因でビルドが失敗する場合。
• ユーザーが 6 から 7 への正確なチェックリストを求めている場合。

使用しないでください：

• アプリが 5.x の場合は、まず capacitor-app-upgrade-v5-to-v6 を使用してください。7.x の場合は capacitor-app-upgrade-v7-to-v8 を使用してください。複数段階の移行計画には capacitor-app-upgrades を使用してください。
• プラグインライブラリのアップグレードには capacitor-plugin-upgrade-v6-to-v7 を使用してください。
• 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、build.gradle、ラッパー、マニフェスト、Kotlin を手動で編集する場合
references/plugins.md	アプリで公式の @capacitor/* プラグイン（App、Device、Haptics、Splash Screen、Status Bar など）を使用している場合

事前確認

ツール	Capacitor 7 の最小要件
Node.js	20 以上（最新の LTS を推奨）
Xcode	16.0 以上
iOS デプロイメントターゲット	14.0
Android Studio	Ladybug 2024.2.1 以上（JDK 21 をバンドル）
Java（Gradle JDK）	21
AGP／Gradle	8.7.2／8.11.1
Android SDK	minSdk 23、compileSdk 35、targetSdk 35

node -v && xcodebuild -version && java -version
git status --short
grep -rn "bundledWebRuntime\|staticPlugins" capacitor.config.*

手順

1. スナップショットで 6.x であることを確認します。注意：minSdk を 23 に、iOS を 14 に引き下げると、古いデバイスのサポートが終了します。ユーザーに伝えてください。

2. 自動移行を実行します：

   npm i -D @capacitor/cli@latest-7
   npx cap migrate
   

   パッケージのバージョンを上げ、iOS のデプロイメントターゲットと Podfile を 14.0 に引き上げ、Gradle ファイルとラッパーを更新して、cap sync を実行します。スキップまたは失敗と報告された手順は、すべて完了してください。

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

   • bundledWebRuntime は削除されました。false の場合は削除してください。true の場合、capacitor.js を読み込むのではなく、バンドラー（Vite、webpack など）でアプリに @capacitor/core をバンドルする必要があります。
   • cordova.staticPlugins は削除されました。静的リンクが必要な Cordova プラグインでは、use-framework を指定する podspec タグを使用する必要があります（cordova-ios 7 以降では framework タグをサポートしていません）。

4. iOS：プロジェクトとすべてのターゲットのビルド設定で iOS Deployment Target = 14.0 に設定し、ios/App/Podfile で platform :ios, '14.0' に設定します。SPM アプリでは、CapApp-SPM/Package.swift のプラットフォームを確認してください。

5. Android：references/android.md を適用します（AGP 8.7.2、Gradle 8.11.1、google-services 4.4.2、Kotlin 1.9.25、configChanges の navigation は任意）。

6. @capacitor/* プラグインを ^7.0.0 に、コミュニティプラグインをそれぞれの Capacitor 7 リリースに更新します。削除された型を references/plugins.md に従って修正してください。

7. 新しい CLI ユーザーではテレメトリーがオプトアウト方式で有効になりますが、CI では実行されません。ユーザーが希望する場合は npx cap telemetry off で無効にしてください。

8. 検証を実行します。

注意点

• JDK 21 が必要です。Capacitor 7 の Android モジュールは Java 21 のソース／ターゲットでコンパイルされるため、JDK 17 の Gradle ランタイムでは invalid source release: 21 が発生します。コードではなく Gradle JDK（IDE と CI）を修正してください。
• minSdkVersion 22 または iOS 13 を引き続き宣言しているコミュニティプラグインもコンパイルできますが、@capacitor/core のピア依存関係に ^6 を宣言しているプラグインでは、npm の ERESOLVE が発生します。アップグレードするか、置き換えてください。ユーザーがリスクを受け入れない限り、--legacy-peer-deps は使用しないでください。
• Device の getInfo() は diskFree、diskTotal、realDiskFree、realDiskTotal を返さなくなりました。他のコードでディスク容量を読み取っていない場合に限り、対応する PrivacyInfo.xcprivacy のディスク容量項目を削除してください。

検証

grep -rn "bundledWebRuntime\|staticPlugins" capacitor.config.*         # expect none
grep -rn "IPHONEOS_DEPLOYMENT_TARGET" ios/App/App.xcodeproj/project.pbxproj | sort -u   # 14.0
grep -n "platform :ios" ios/App/Podfile 2>/dev/null                     # '14.0'
grep -n "gradle:8.7.2\|google-services:4.4.2" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.11.1
grep -n "SdkVersion" android/variables.gradle                           # 23 / 35 / 35
grep -rnE "AppUrlOpen|AppRestoredResult|DeviceBatteryInfo|DeviceLanguageCodeResult|Haptics(Impact|Notification)(Options|Type|Style)|SplashScreen(Show|Hide)Options|diskFree|diskTotal" src/
npx cap sync
cd android && ./gradlew assembleDebug

その後、Xcode 16 以降で iOS をビルドし、両方のプラットフォームを起動します。

エラー処理

エラー	修正方法
Migrate can only be used on Capacitor 6, please use the CLI in Capacitor 6 to upgrade to 6 first	まず capacitor-app-upgrade-v5-to-v6 を実行します。
Capacitor 7 requires JDK 21 or higher. Some steps may fail. / invalid source release: 21	Gradle JDK を 21 に設定します（Android Studio Ladybug に同梱されています）。CI でも設定してください。
Skipped updating deployment target	Xcode と Podfile で iOS 14.0 を手動で設定します（手順 4）。
Unable to find "<text>" in <file>. Try updating it manually	references/android.md の差分を適用します。
Module '"@capacitor/app"' has no exported member 'AppUrlOpen' (または類似のエラー)	references/plugins.md に記載されている置換後の型名に変更します。
ERESOLVE unable to resolve dependency tree on @capacitor/core	まだ v6 をピア依存関係として指定しているプラグインがあります。v7 リリースにアップグレードしてください。