debugging-capacitor

Capacitor アプリのデバッグ

どのレイヤー（Web、ブリッジ、ネイティブ、OS 設定）に問題があるかを特定し、適切なインスペクターで検証してから、最小限の修正を行います。

使用するタイミング

次の場合に使用します。

• アプリが白い画面／空白の画面になる、起動時にクラッシュする、またはネイティブ呼び出し後にフリーズする。
• エラー "<Name>" plugin is not implemented on ios|android または "<Name>.<method>()" is not implemented on ... が発生する。
• デバイス上でのみネットワークリクエストに失敗する：net::ERR_CLEARTEXT_NOT_PERMITTED、ATS の「requires the use of a secure connection」、CORS エラー。
• 権限の確認プロンプトが表示されない、または常に拒否される。
• ライブリロード（cap run --url、server.url）で空白の画面または「Webpage not available」が表示される。
• Capacitor 8.5+／Xcode 27 への更新後に、appUrlOpen が反応しない、ユニバーサルリンクでアプリは開くものの何も起きない、JS の pause／resume やカスタム AppDelegate コードが実行されなくなった。
• ユーザーから「Capacitor アプリをどうデバッグ／検査すればよいか」と質問された。

次の場合は使用しないでください。

• ログやクラッシュレポートのストリーミング、フィルタリング、保存のみが必要 → ios-android-logs。
• AppDelegate から SceneDelegate への移行そのものを実施する → capacitor-uiscene-migration。
• ディープリンク、AASA、assetlinks をゼロから設定する → capacitor-deep-linking。
• カクつき、起動の遅さ、バンドルサイズ、メモリの調整 → capacitor-performance。
• 本番環境で Sentry／Crashlytics／Datadog を使用する → capacitor-native-observability。
• 単体テスト／E2E テストを作成する → capacitor-testing。AI／MCP によるデバイス自動化 → capacitor-mcp。
• バージョン更新による Gradle／Xcode のビルド失敗 → capacitor-app-upgrades、Pods／SPM の依存関係解決 → cocoapods-to-spm。
• プッシュトークン／配信の問題 → capacitor-push-notifications、キーボードの重なり → capacitor-keyboard、ノッチ／インセット → safe-area-handling。

トリアージのワークフロー

1. コードに手を加える前に事実を集めます：プラットフォーム、シミュレーターかデバイスか、デバッグかリリースか、Capacitor のバージョン（npx cap doctor）、直近の変更内容（アップグレード、プラグインの追加、設定の編集）、エラーの正確な文言。
2. 問題のレイヤーを分類します：
   • JS の例外、fetch の失敗、不正なルート → Web レイヤー：WebView インスペクター（Safari／chrome://inspect）を開きます。references/webview-inspection.md を参照してください。
   • plugin is not implemented → ブリッジ／登録：ネイティブコードがバイナリに含まれていないか、JS を注入できていません。下記の「エラー処理」を参照してください。
   • プロセスが終了する／EXC_BAD_ACCESS／FATAL EXCEPTION → ネイティブレイヤー：デバッガーを接続して Xcode／Android Studio から実行します。references/native-debugging.md を参照してください。
   • 8.5／Xcode 27 以降、Android では動作するが iOS では動作しない、リンク／ライフサイクル関連 → UIScene。references/uiscene-regressions.md を参照してください。
3. 同期し直して再現します：npm run build && npx cap sync を実行してから、ネイティブアプリを再ビルドします。public/ の古いアセットや未同期のプラグインが、「ブラウザーでは動作するがデバイスでは壊れる」という報告の大半の原因です。
4. ネイティブコンソールで Capacitor 自身のメッセージを確認します。iOS は ⚡️ Loading app at ...、⚡️ [log] - ...、⚡️ ERROR: Unable to load ... を stdout に出力します（Xcode のコンソール、simctl launch --console-pty、devicectl ... launch --console で確認できます。Console.app には表示されません）。Android のログはタグ Capacitor、JS コンソールのログは Capacitor/Console に出力されます。ログのコマンドは ios-android-logs にあります。
5. 大がかりな変更を加える前に、根本原因と修正案をユーザーに伝えます（ios/／android/ の削除、project.pbxproj の編集、ATS のグローバルな無効化など）。
6. 修正を適用し、検証手順を実行します。

ツール一覧

必要な操作	iOS	Android
DOM／JS／ネットワークを調査する	Safari > Develop > device > app	chrome://inspect/#devices
ネイティブのブレークポイントを設定する	Xcode（npx cap open ios）、LLDB	Android Studio debugger（npx cap open android）
CLI から対象デバイスで実行する	npx cap run ios --target <id>	npx cap run android --target <id>
対象デバイスを一覧表示する	npx cap run ios --list	npx cap run android --list
URL／ディープリンクを開く	xcrun simctl openurl booted <url>；デバイスの場合：xcrun devicectl device process openURL --device <id> <url>	adb shell am start -W -a android.intent.action.VIEW -d "<url>" <appId>
権限をリセット／付与する（シミュレーター）	xcrun simctl privacy booted reset all <appId>	adb shell pm revoke <appId> android.permission.CAMERA / adb shell pm clear <appId>
プッシュ通知を偽装する（シミュレーター）	xcrun simctl push booted <appId> payload.json	実際の FCM メッセージを送信する
標準出力を有効にして起動する	xcrun simctl launch --console-pty booted <appId>；デバイスの場合：xcrun devicectl device process launch --console --device <id> <appId>	adb logcat
プロファイルを取得する	Instruments / xcrun xctrace record --template 'Time Profiler'	Android Studio Profiler

詳細と注意事項：references/device-cli.md。

ライブリロードのクイック手順

• Capacitor 9（@next）：npx cap run ios --url http://192.168.1.68:5173。以前の -l/--live-reload、--host、--port、--https フラグは削除されています。
• Capacitor 8.5（安定版）：npx cap run ios -l --host 192.168.1.68 --port 5173（https の開発サーバーでは --https を追加します）。
• Android エミュレーター／USB：--forwardPorts 5173:5173 を指定すると adb reverse が実行され、http://localhost:5173 を利用できます。
• 開発サーバーは 0.0.0.0 にバインドする必要があります。スマートフォンと Mac を同じ Wi-Fi に接続してください。iOS ではローカルネットワークへのアクセスを求められることがあります。拒否するとページが読み込まれないため、Settings > Privacy & Security > Local Network で再度有効にしてください。
• capacitor.config.* に server.url / server.cleartext を含めた状態でリリースしないでください。リリース前に grep で確認してください。

エラー処理

エラー／症状	考えられる原因	対処方法
"Foo" plugin is not implemented on ios	プラグインがネイティブプロジェクトに含まれていない、または JS の注入がブロックされている	npm i <plugin> → npx cap sync ios を実行します。SPM の場合は、ios/App/CapApp-SPM/Package.swift にプラグインが記載されていることを確認します。CocoaPods の場合は、ios/App/Podfile を確認します。Info.plist から WKAppBoundDomains を削除するか、ios.limitsNavigationsToAppBoundDomains: true を設定します。
"Foo" plugin is not implemented on android	Gradle が同期されていない、またはサービスワーカーがページをインターセプトしている	npx cap sync android を実行し、次に File > Sync Project with Gradle Files を選択します。ネイティブビルドでサービスワーカーを無効化または登録解除します。
"Foo.bar()" is not implemented on web	ブラウザーでネイティブ専用メソッドを呼び出している	Capacitor.isNativePlatform() / Capacitor.isPluginAvailable('Foo') でガードします。
⚡️ ERROR: Unable to load .../index.html ／白い画面	webDir が間違っている、またはファイルがコピーされていない	Web をビルドし、webDir が出力フォルダーと一致していることを確認してから、npx cap copy を実行します。
白い画面で、ネイティブエラーがない	最初の描画前に JS がクラッシュしている、または <base href>／絶対アセットパスが不正	WebView のコンソールを確認します。capacitor://localhost / https://localhost 配下で解決される相対パスまたはルート相対パスを使用します。
net::ERR_CLEARTEXT_NOT_PERMITTED	Android が HTTP をブロックしている（API 28 以降）	HTTPS を使用します。開発時のみ、server.cleartext: true または開発ホストに限定した network_security_config.xml を使用します。
"The resource could not be loaded because the App Transport Security policy requires the use of a secure connection."	iOS の ATS	HTTPS を使用します。開発時のみ、グローバルな NSAllowsArbitraryLoads ではなく、開発ホストに対する NSExceptionDomains を設定します。
デバイス上でのみ API から CORS エラーが発生する	オリジンが capacitor://localhost（iOS）／https://localhost（Android）になっている	サーバー側でこれらのオリジンを許可するか、CapacitorHttp（plugins.CapacitorHttp.enabled: true）を有効にして fetch／XHR をネイティブ経由で処理します。
権限リクエスト時にクラッシュする（iOS、This app has crashed because it attempted to access privacy-sensitive data without a usage description）	NS*UsageDescription が不足している	キーを ios/App/App/Info.plist に追加します。
Android で権限が常に denied になる	<uses-permission> がない、またはユーザーが「許可しない」を 2 回選択した	AndroidManifest.xml に追加し、設定画面を開くようユーザーに案内します。
Xcode で No such module 'Capacitor' が発生する	CocoaPods 使用時に .xcodeproj を開いている、または SPM パッケージが解決されていない	Pods の場合：App.xcworkspace を開き、npx cap sync ios を実行します。SPM の場合：File > Packages > Reset Package Caches を選択します。詳しくは cocoapods-to-spm を参照してください。
Unable to boot device in current state: Booted	シミュレーターがすでに起動している	エラーではありません。デバイス ID として booted を使用します。
iOS でのみ 8.5 以降、appUrlOpen／ユニバーサルリンクが反応しない	AppDelegate の open url／continue userActivity が呼び出されなくなった	references/uiscene-regressions.md を参照してください。
JS の pause／resume が発火しなくなる	カスタム SceneDelegate にプロキシ転送がない、またはロジックが applicationDidEnterBackground に残っている	references/uiscene-regressions.md を参照してください。

症状に応じたその他の対処方法については、references/common-failures.md を参照してください。

検証

修正を行ったら、必ず次の方法で確認します。

1. npx cap doctor で @capacitor/core、cli、ios、android のバージョンが一致していることを確認します。
2. npm run build && npx cap sync が、プラグイン不足に関する警告なしで完了することを確認します。
3. ネイティブコンソールに ⚡️ Loading app at capacitor://localhost...（iOS）が表示されること、または Capacitor/Console エラーがないこと（Android）を確認します。
4. 起動時に WebView インスペクターのコンソールにエラーがないことを確認します。
5. シミュレーター／エミュレーターと実機の両方で、問題を再現する手順をそのまま再実行します。リリースビルドでのみ発生するバグの場合は、リリースビルドでも確認します（cap run はデフォルトで Debug をビルドします。iOS では --configuration Release を指定でき、Android のリリースビルドは Android Studio または Gradle で実行します）。
6. リンク／ライフサイクルに関する修正では、simctl openurl / adb shell am start を使い、コールド起動（アプリを終了した状態）とウォーム起動（アプリをバックグラウンドにした状態）をテストします。また、バックグラウンドからフォアグラウンドへ一度切り替え、pause と resume が発火することを確認します。
7. 出荷前に、grep -n "server" capacitor.config.* を実行し、url／cleartext が残っていないことを確認します。

参考資料

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

ファイル	読み込むタイミング
references/webview-inspection.md	Safari／Chrome インスペクターの接続、インスペクターにアプリが表示されない場合、リリースビルドのデバッグ、起動初期の JS エラー
references/native-debugging.md	ネイティブクラッシュ、プラグイン内のブレークポイント、LLDB、Android Studio デバッガー、Instruments／xctrace、メモリリーク
references/device-cli.md	ターミナルからのシミュレーター／デバイスの操作：インストール、起動、URL のオープン、権限、プッシュ、アプリコンテナー
references/uiscene-regressions.md	iOS のディープリンク、ユニバーサルリンク、コールドスタート時の URL、一時停止／再開、または Capacitor 8.5／Xcode 27 へのアップデート後に壊れた AppDelegate コード
references/common-failures.md	白い画面、プラグインが実装されていないエラー、ネットワーク、権限、ライブリロードの詳細な修正方法

リソース

• https://capacitorjs.com/docs/ios/troubleshooting
• https://capacitorjs.com/docs/android/troubleshooting
• https://capacitorjs.com/docs/guides/live-reload
• https://capacitorjs.com/docs/updating/8-5
• https://capacitorjs.com/docs/cli/commands/run