capacitor-app-upgrade-v5-to-v6

Capacitor アプリの v5 から v6 へのアップグレード

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

使用するタイミング

• 以下のスナップショットで @capacitor/core が 5.x で、ユーザーが 6.x を希望している場合。
• アップグレード後に、Android ユーザーの localStorage／Cookie が失われた場合、ローカル（npm 以外）の iOS プラグインで "<Name>" plugin is not implemented on ios が表示される場合、iOS でピンチズームが機能しなくなった場合、または addListener に関する TypeScript エラーが発生した場合。
• ユーザーが 5 から 6 への正確なチェックリストを求めている場合。

使用しない場合：

• 4.x のアプリの場合は、まず capacitor-app-upgrade-v4-to-v5 を使用します。6.x のアプリの場合は capacitor-app-upgrade-v6-to-v7 を使用します。複数バージョンをまたぐ移行計画には capacitor-app-upgrades を使用します。
• プラグインライブラリのアップグレードには capacitor-plugin-upgrade-v5-to-v6 を使用します。
• iOS を CocoaPods から SPM に移行する場合（6 では実験的機能）は、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/* プラグインを使用している場合、または addListener の戻り値を保持している場合

事前確認

ツール	Capacitor 6 の最小要件
Node.js	18 以上（最新の LTS を推奨）
Xcode	15.0 以上
Android Studio	Hedgehog 2023.1.1 以上
Java（Gradle JDK）	17
AGP／Gradle	8.2.1／8.2.1
Android SDK	minSdk 22、compileSdk 34、targetSdk 34
iOS デプロイメントターゲット	13.0（変更なし）

node -v && xcodebuild -version && java -version
git status --short
grep -rn "androidScheme" capacitor.config.*   # decide the scheme BEFORE migrating

手順

1. スナップショットで 5.x であることを確認します。

2. 最初に androidScheme を決定します（判断が必要です。不明な場合はユーザーに確認してください）。Capacitor 6 では、既存アプリのデフォルトが https になります。スキームを変更すると WebView のオリジンも変わるため、インストール済みアプリの localStorage、IndexedDB、Cookie、サービスワーカーは読み取れなくなります。

   • 現在 androidScheme が設定されていない場合：ユーザーデータを保持するため、server: { androidScheme: "http" } を追加します。
   • すでに "https" の場合：この項目は削除できます。

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

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

   出力を確認し、失敗として報告されたすべての手順を完了します。

4. iOS：

   • プラグインクラスは自動登録されなくなりました。npm プラグインは CLI が生成するリストで処理されます。アプリのターゲットに記述されたローカルプラグイン（カスタムコードのガイドを参照）では、capacitorDidLoad() をオーバーライドして bridge?.registerPluginInstance(MyPlugin()) を呼び出す CAPBridgeViewController のサブクラスが必要です。また、Main.storyboard では、そのサブクラスをビューコントローラーのカスタムクラスとして指定する必要があります。
   • ズームはデフォルトで無効になっています。アプリでピンチズームを使用していた場合は、Capacitor の設定で zoomEnabled: true を設定します。

5. Android：references/android.md を適用します（AGP 8.2.1、Gradle 8.2.1、google-services 4.4.0、compileSdk、Kotlin 1.9.10）。

6. すべての @capacitor/* プラグインを ^6.0.0 に、コミュニティプラグインをそれぞれの Capacitor 6 対応リリースに更新します。references/plugins.md に従ってコードを修正します。

7. 検証を実行します。

注意点

• addListener の戻り値は Promise<PluginListenerHandle> のみになりました。const h = Plugin.addListener(...); h.remove() はコンパイルできなくなります。const h = await Plugin.addListener(...) を使用してください。
• Camera は Android Photo Picker を使用するようになりました。Android ではギャラリーをキャンセルすると、他のプラットフォームと同様に "User cancelled photos app" で拒否されます。エラー判定を更新してください。
• iOS の Filesystem stat() は、ctime／mtime を文字列ではなく数値として返します。
• saveToGallery: true の場合、または他のプラグインで必要な場合は、READ_MEDIA_IMAGES／ストレージの権限を削除しないでください。

検証

grep -rn "androidScheme" capacitor.config.*                 # explicit decision recorded
grep -n "compileSdkVersion rootProject" android/app/build.gradle   # expect none (now compileSdk)
grep -n "gradle:8.2.1\|google-services:4.4.0" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.2.1
grep -n "SdkVersion" android/variables.gradle                # 22 / 34 / 34
grep -rnE "= *[A-Za-z]+\.addListener\(" src/                 # each must be awaited
grep -rn "registerPluginInstance" ios/App/App/               # present if the app has local plugins
npx cap sync
cd android && ./gradlew assembleDebug

Xcode 15 以降で iOS をビルドして起動します。v5 のビルドがインストールされていたデバイスでアプリをそのままアップグレードし、ログイン状態と localStorage が保持されていることを確認します。

エラー処理

エラー	修正方法
Migrate can only be used on capacitor 5 and above, please use the CLI in Capacitor 5 to upgrade to 5 first	先に capacitor-app-upgrade-v4-to-v5 を実行してください。
Capacitor 6 requires JDK 17 or higher. Some steps may fail.	Gradle の JDK を 17 以上に設定してください。
Unable to find "<text>" in <file>. Try updating it manually	references/android.md の差分を適用してください。
"<Plugin>" plugin is not implemented on ios（ローカルプラグイン）	CAPBridgeViewController のサブクラス（手順 4）に登録してください。
Property 'remove' does not exist on type 'Promise<PluginListenerHandle>'	addListener の呼び出しに await を付けてください。
Android でユーザーがログアウトされた／データが消えた	スキームが変更されています。以前の androidScheme の値に戻してください。