cordova-to-capacitor

Cordova から Capacitor への移行

Cordova アプリを段階的に Capacitor へ移行します。まず Capacitor に移行し、プラグインを一つずつ移行して、最後に Cordova を削除します。

使用するタイミング

以下の場合に使用します。

• config.xml、platforms/、plugins/、cordova-android／cordova-ios、または cordova-plugin-* が存在し、ユーザーが Capacitor を使いたい場合。
• コードが deviceready を待機している、または navigator.camera、window.plugins.*、cordova.plugins.*、@awesome-cordova-plugins/*、@ionic-native/* を呼び出している場合。
• 移行後、初回起動時にデータが失われる、Cordova プラグインの動作がなくなる、または Capacitor 9 のビルドエラーで Cordova のシンボルが参照される場合。

以下の場合には使用しないでください。

• Cordova プラグインの Java／Objective-C を Capacitor プラグインとして書き換える場合（プラグインレベルの移植）→ Capacitor プラグインのドキュメントに従ってください。既存の代替プラグインには capacitor-plugins を使用してください。
• Capacitor のメジャーバージョンをアップグレードする場合 → capacitor-app-upgrades を使用してください。
• Appflow Live Updates（cordova-plugin-ionic）を置き換える場合 → ionic-appflow-migration と capgo-live-updates を使用してください。
• フレームワークのビルド設定（Angular の出力パス、Vite）の場合 → framework-to-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.includes('cordova')||name.includes('phonegap')||name.startsWith('@capacitor/')||name.startsWith('@capgo/')||name.startsWith('@ionic-native/')||name.startsWith('@awesome-cordova-plugins/')||name.startsWith('@ionic-enterprise/'))out.push(section+'.'+name+'='+version)}}if(pkg.cordova)out.push('cordova.plugins='+Object.keys(pkg.cordova.plugins||{}).join(','));console.log(out.sort().join('\n'))"

関連する設定とプラットフォームのパス： !find . -maxdepth 3 -not -path '*/node_modules/*' \( -name 'config.xml' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './ios' -o -path './android' -o -path './platforms' -o -path './plugins' -o -name 'www' \)

判断の決め手となる主な違い

• Capacitor のネイティブプロジェクト（ios/、android/）はコミットして編集するソースコードです。npx cap sync によって再生成されることはありません。Cordova の platforms/ はビルド成果物です。
• Capacitor は、cap sync が Cordova プラグインに対して行う処理を除き、ビルド時に config.xml やプラグインの <config-file>／<edit-config> の編集を適用しません。権限、エンタイトルメント、Info.plist のキーは、一度だけ手動で編集する必要があります。
• Cordova プラグインは Capacitor でも引き続き動作します（npm でインストールし、cap sync で適用します）。フックと <variable> のインストール時プロンプトは実行されません。変数は capacitor.config.* の cordova.preferences で設定してください。
• オリジンの変更：デフォルトでは、アプリは iOS では capacitor://localhost、Android では https://localhost から配信されます。既存の localStorage、IndexedDB、Cookie、Service Worker のデータは旧オリジンに紐づいているため、スキームを維持しない限り、アップデート後に「失われた」ように見えます（references/config-and-data.md を参照）。
• deviceready は不要です。プラグインはインポート後に利用できます。引き続き Cordova プラグインを使用する場合、Capacitor の Cordova レイヤーが cordova.js を注入するため、deviceready は引き続き発生します。

Capacitor 9：Cordova ランタイムは任意です

Capacitor 9 では、インストール済みプラグインに Cordova プラグインが 1 つ以上含まれる場合に限り、npx cap sync によって Cordova 互換レイヤーが組み込まれます。

• Android：Cordova プラグインがない場合、capacitor-cordova-android ／ capacitor-cordova-android-plugins モジュールは settings.gradle と app/build.gradle から削除されます。
• iOS：CapacitorCordova は Podfile または Package.swift に追加されなくなります。

影響：

• 最後の Cordova プラグインを削除すると、アプリが小さくなり、cordova.js も削除されます。これは望ましいことですが、Cordova プラグインがインストールされていない状態で、Cordova のシンボル（com.getcapacitor.cordova.CordovaPlugin、CDVPlugin、CDVPluginHandleOpenURL、window.cordova）を参照するアプリ／ネイティブコードがあると、コンパイルに失敗するか、実行時に undefined になります。
• ランタイムを強制的に含める設定フラグはありません。該当する参照を削除するか、Cordova プラグインをインストールしたままにしてください。
• ランタイムがなくなると、JavaScript に残っている deviceready リスナーは実行されません。最後の Cordova プラグインを削除する前に、これらを削除してください。
• Capacitor 8 ではランタイムは常にバンドルされるため、この問題が表面化するのはアップグレード時のみです。9 に移行する前に確認してください。

手順

1. 監査します（編集前にユーザーに報告してください）。
   • cordova --version、cordova platform ls、cordova plugin ls（または package.json の cordova.plugins）。
   • config.xml：widget の id、version、<preference>、<platform> ブロック、<access>／<allow-navigation>、アイコン／スプラッシュ画面。
   • インストール済みの WebView プラグイン（cordova-plugin-ionic-webview、cordova-plugin-wkwebview-engine）と現在のスキーム／ホスト名。データを保持できるかどうかを左右します。
   • 各プラグインについて、代替手段があるか、Cordova プラグインとして保持するか、または移行の妨げとなるかを確認します。references/plugin-mapping.md を使用してください。
   • deviceready、navigator.* の Cordova グローバル、window.plugins、Ionic Native ラッパーを使用しているコード。
2. 既存のプロジェクトに Capacitor をインストールし、同じアプリ ID を維持します。

   npm install @capacitor/core @capacitor/ios @capacitor/android
   npm install -D @capacitor/cli
   npx cap init "<name from config.xml>" <widget id from config.xml> --web-dir www
   

   cap init は config.xml の設定を Capacitor の設定内の cordova.preferences に読み込みます。Web ビルドの出力先が webDir になるようにしてください（Ionic Angular の場合は www）。
3. 最初のリリース前に、データを保持するか（スキーム）を決定します。references/config-and-data.md を参照してください。
4. npm run build && npx cap add ios && npx cap add android を実行します。package.json の依存関係に記載された Cordova プラグインは、新しいネイティブプロジェクトにインストールされます。互換性がないと判明しているプラグインは警告とともにスキップされます。
5. ネイティブ設定を手動で移行します：使用目的の説明文、権限、エンタイトルメント、URL スキーム、画面の向き、スプラッシュ画面／アイコン（npx @capacitor/assets generate）。references/config-and-data.md を参照してください。
6. プラグインを 1 つずつ置き換え（references/plugin-mapping.md）、コールバックコードを Promise に変換し（references/code-patterns.md）、npx cap sync を実行して、そのつど実機でテストします。
7. Cordova に依存するものがなくなったら、Cordova を削除します（「削除」を参照）。代替手段がない Cordova プラグインは保持してください。それらは動作します。
8. Capacitor のビルドが安定したら、Capgo ライブアップデートを案内します（capgo-live-updates）。

削除

両プラットフォームですべてのフローを検証した後に限り、次の手順を実行します。

npm uninstall cordova cordova-ios cordova-android
npm uninstall cordova-plugin-ionic-webview cordova-plugin-splashscreen cordova-plugin-statusbar cordova-plugin-ionic-keyboard
rm -rf platforms plugins
git mv config.xml config.xml.bak   # keep for reference until release
npx cap sync
grep -rn "deviceready\|cordova\.\|window\.plugins" src --include=*.ts --include=*.js --include=*.tsx --include=*.vue

Cordova プラグインが残っていない場合は、package.json から cordova ブロックを削除します。cordova plugin rm のループは実行しないでください。削除する platforms/ を編集するだけです。

検証

• npx cap sync の出力に、意図した Cordova プラグインのみが表示され、「incompatible」に関する予期しない表示がないこと。
• npx cap doctor で、core、cli、ios、android のバージョンが一致していること。
• 同じ bundle ID と、より高い build number を使い、既存のストア版の上に Capacitor ビルドをインストールして、ユーザーが引き続きログイン状態であり、ローカルデータが存在することを実機で確認します。
• 移行したすべてのプラグインを実機でテストします（カメラ、ファイル、プッシュトークン、位置情報、購入）。
• Capacitor 9：最後の Cordova プラグインを削除した後、grep -rn "CapacitorCordova\|capacitor-cordova-android" ios android の結果が空で、ネイティブビルドが成功すること。

エラー対応

エラー／症状	解決方法
同期中に Found 1 incompatible Cordova plugin for ios, skipped install: が表示される	このプラグインは Capacitor の既知の互換性のないプラグインの一覧に含まれています。Capacitor の同等プラグインを使用してください
Cordova ビルドから更新した後、ユーザーデータ／ログイン情報が消える	オリジンが変更されています。server.iosScheme: 'ionic'（旧 ionic-webview の iOS）を設定するか、以前の Android のスキーム／ホスト名に合わせてから、再度配布してください
deviceready ハンドラーが実行されない	Cordova プラグインがない Capacitor 9 を使用しているか、Cordova のグローバル変数を前提としたコードを使用しています。プラグインを直接呼び出してください
"Camera" plugin is not implemented on ios（プラグイン名は問いません）	ネイティブプロジェクトにプラグインがインストールされていません。npx cap sync を実行し、npx cap ls を確認してください
ビルド時に Cordova プラグインの変数（API キーなど）が見つからない	capacitor.config.* の cordova.preferences に追加し、npx cap sync を実行してください
Capacitor 9 へのアップグレード後、Android で cannot find symbol class CordovaPlugin、または iOS で No such module 'Cordova' が表示される	Cordova ランタイムはバンドルされなくなりました。その参照を削除するか、Cordova プラグインを引き続き使用してください
インストールフックのあるプラグインが何もしない	Capacitor ではフックは実行されません。フックによるファイル変更を手動で再現してください
cap add の後に白い画面が表示される	webDir が正しくないか、ウェブビルドが実行されていません。npm run build を実行してから npx cap sync を実行してください

参考資料

• references/plugin-mapping.md - Cordova プラグインから Capacitor／Capgo への置き換え表、互換性のないプラグインの一覧、Cordova プラグインを引き続き使用する場合のガイダンス。
• references/config-and-data.md - config.xml のマッピング、設定項目、スキームとデータ保持、権限、スプラッシュ画面／アイコン。
• references/code-patterns.md - 一般的なプラグインでのコールバックからプロミスへの変換。

関連スキル：capacitor-plugins、capacitor-app-upgrades、capgo-live-updates、capacitor-app-store。