capacitor-app-upgrade-v4-to-v5

Capacitor アプリを v4 から v5 にアップグレード

Capacitor 4 のアプリを Capacitor 5 に移行します。情報源：https://capacitorjs.com/docs/updating/5-0

使用する場合

• 以下のスナップショットで @capacitor/core が 4.x で、ユーザーが 5.x を希望している場合。
• Capacitor 5 への更新後に、Namespace not specified、Java 11 と 17 の不一致、または AGP 8 のエラーが原因で Android ビルドに失敗する場合。
• iOS、Android、または公式プラグイン向けの正確な 4 -> 5 チェックリストを求められた場合。

使用しない場合：

• アプリが 5.x 以降の場合 -> capacitor-app-upgrade-v5-to-v6（その後 v6-to-v7、v7-to-v8）。複数段階の移行計画 -> capacitor-app-upgrades。
• プラグインライブラリをアップグレードする場合 -> capacitor-plugin-upgrade-v4-to-v5。
• アプリが 3.x の場合 -> 先に 4 へアップグレードしてください（5.x の npx cap migrate は 4 未満のプロジェクトを拒否します）。

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

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/* プラグイン（Camera、Device、Push、Local Notifications、Google Maps など）を使用している場合

事前確認

ファイルを変更する前に確認して報告してください。最低要件を満たしていない場合は、ツールをアップグレードするようユーザーに依頼してください。

ツール	Capacitor 5 の最低要件
Node.js	16+（最新の LTS を推奨）
Xcode	14.1+
Android Studio	Flamingo 2022.2.1+（JDK 17 がバンドルされています）
Java（Gradle JDK）	17
AGP / Gradle	8.0.0 / 8.0.2
Android SDK	minSdk 22、compileSdk 33、targetSdk 33
iOS のデプロイメントターゲット	13.0（v4 から変更なし）

node -v
xcodebuild -version
java -version
git status --short   # start from a clean tree so the migration diff is reviewable

手順

1. スナップショットで @capacitor/core が 4.x であることを確認します。4 未満の場合は中止し、先に 3 -> 4 のアップグレードに案内してください。

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

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

   これにより @capacitor/* パッケージが更新され、variables.gradle、AGP、Gradle ラッパーが更新され、package が namespace に移行され、iOS アプリアイコンのセットが縮小され、cap sync が実行されます。出力を確認してください。完了できなかった手順はすべて表示されるため、手動で対応する必要があります。

3. git diff を確認します。その後、CLI がスキップした項目をすべて完了します。

   • iOS：ios/.gitignore で App/Podfile.lock を App/output に置き換えます（今後は Podfile.lock をコミットします）。必要に応じて AppIcon.appiconset を 1024x1024 のアイコン 1 つに縮小します。
   • Android：references/android.md の変数テーブルと差分を適用します（AGP 8.0.0、Gradle 8.0.2、google-services 4.3.15、namespace、Jetifier、Kotlin 1.8.20）。
   • 設定：server.androidScheme が設定されていない場合は、capacitor.config.* に androidScheme: "http" を追加します。Capacitor 6 ではデフォルトが https に変わるため、WebView のオリジンが変わり、localStorage、IndexedDB、Cookie が消去されます。今のうちに値を固定すれば、将来のデータ損失を防げます。代わりに https を選ぶ場合は、事前にユーザーに確認してください。

4. すべての公式プラグインを ^5.0.0 に更新し、コミュニティプラグインを Capacitor 5 対応リリースに更新します。references/plugins.md のコード変更を適用します。

5. Gradle ファイルに AGP 7 の設定が残っている場合は、Android Studio で Tools -> AGP Upgrade Assistant を実行します。

6. 以下の検証を実行します。

落とし穴

• android.enableJetifier=true を削除すると、依存関係に古い android.support.* ライブラリを使用しているものがある場合、ビルドが失敗します。まず node_modules とネイティブ依存関係を grep してください。不明な場合は Jetifier を残してください。
• namespace は、古いマニフェストの package 値と一致している必要があります。両者が異なる場合、applicationId ではありません。
• Device プラグイン：getId() は { identifier } を返すようになり、uuid はなくなりました。iOS 16 以降では、DeviceInfo.name はユーザーが割り当てたデバイス名のエンタイトルメントがない場合、汎用名を返します。
• Android 13（targetSdk 33）：Push Notifications と Local Notifications は、実行時に checkPermissions() / requestPermissions() を呼び出す必要があります。呼び出さないと何も表示されません。

検証

grep -rn "package=" android/app/src/main/AndroidManifest.xml          # expect no package attribute
grep -n "namespace" android/app/build.gradle                          # expect namespace "<id>"
grep -n "gradle:8.0.0\|google-services" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties  # gradle-8.0.2
grep -n "SdkVersion" android/variables.gradle                         # 22 / 33 / 33
grep -rn "androidScheme" capacitor.config.*                           # explicit value present
grep -rn "\.uuid\b" src/                                              # no Device uuid leftovers
npx cap sync
cd android && ./gradlew assembleDebug

続いて、Xcode 14.1 以降で iOS をビルドし（または npx cap run ios を実行し）、両方のプラットフォームを起動してください。保存データ（ログイン情報、localStorage）がアップグレード後も保持されていることを確認してください。

エラー処理

エラー	対処方法
Migrate can only be used on capacitor 4 and above, please use the CLI in Capacitor 4 to upgrade to 4 first	プロジェクトは 3.x です。まず 4 にアップグレードしてください。
Capacitor 5 requires JDK 17 or higher. Some steps may fail.	Gradle の JDK を 17 に設定し（Android Studio の Settings -> Build Tools -> Gradle）、再実行してください。
Unable to find <file>. Try updating it manually	references/android.md の該当する差分を適用してください。
Found namespace in build.gradle already, skipping migration	情報メッセージです。マニフェストに package= が残っていないことを確認してください。
Namespace not specified (Gradle)	失敗しているモジュールの android {} ブロックに namespace "<package id>" を追加してください。サードパーティ製プラグインの場合は、Capacitor 5 対応版に更新してください。
Android Gradle plugin requires Java 17 to run. You are currently using Java 11.	Gradle の JDK を 17 に切り替えてください。
Android でアップグレード後にデータが失われる／ログアウトされる	androidScheme が変更されています。インストール済みアプリで使用されていたスキームに戻してください（v4 のデフォルトは http です）。