トラブルシューティング

Capgo の利用中に発生する可能性のある一般的な問題と、その解決方法をご紹介します。

🚀 エキスパートによるサポートが必要ですか？

複雑な問題でお困りですか？当社のエキスパートチームが解決をサポートします。パーソナライズされたサポート、code のレビュー、そしてお客様のニーズに合わせたカスタムソリューションを提供します。

プロフェッショナルサポートを受ける

アップロード失敗

bundleのuploadに失敗する場合は、以下を再確認してください：

• アプリの App ID が capacitor.config.ts Capgo ダッシュボードのアプリと一致しているか
• Capacitor プロジェクトのルートからアップロードコマンドを実行しているか
• Web アセットがビルド済みで最新か

高度なuploadオプション

Capgo CLI では、一般的なuploadの問題を解決するための追加フラグが用意されています：

• --tus：以下のを使用します tus 再開可能なアップロードプロトコル 大きなbundleのアップロードや不安定なネットワーク環境でも、より確実にアップロードを行うために。bundleが10MBを超える場合や接続が不安定な場合は、以下を使用することを検討してください： --tus:

  npx @capgo/cli@latest bundle upload --tus

• --package-json と --node-modules：Capgo にルートディレクトリの場所を伝えます package.json と node_modules アプリが monorepo や npm workspace のような標準外の構成を使用している場合に指定します。ルートへのパスを package.json および --node_modules path:

  npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  アプリの依存関係を正しくbundleするために、Capgo はこの情報を必要とします。

これらのフラグは、次のような他のオプションと組み合わせて使用できます： --channel 必要に応じて組み合わせてください。詳細は Capgo CLI のドキュメントを 参照して、利用可能なuploadオプションの全容を確認してください。

uploadでまだ問題が解決しない場合は、 Capgo サポート までお問い合わせください。

アップデートのデバッグ

Live Updatesで問題が発生している場合、Capgo のdebugコマンドがトラブルシューティングに役立ちます。使い方は以下の通りです：

1. プロジェクトディレクトリで次のコマンドを実行してください：

   npx @capgo/cli@latest app debug

2. デバイスまたはエミュレータでアプリを起動し、アップデートをトリガーする操作（例：新しいbundleをアップロードした後にアプリを再起動するなど）を行ってください。

3. デバッグコマンドの出力を確認してください。アップデートプロセスに関する以下の情報がログに記録されます：

   • アプリがアップデートを確認したタイミング
   • アップデートが見つかったかどうか、およびそのバージョン
   • アップデートのダウンロードとインストールの進捗状況
   • アップデートプロセス中に発生したエラー

4. デバッグログを使用して、問題が発生している箇所を特定してください。例：

   • アップデートが見つからない場合は、bundleが正常にアップロードされているか、およびアプリが正しいchannelを使用するように設定されているかを再確認してください。
   • アップデートはダウンロードされるがインストールされない場合は、正しく呼び出されているかを確認してください： CapacitorUpdater.notifyAppReady() また、アプリが完全に終了され、その後再起動されたことも確認してください。
   • エラーメッセージが表示された場合は、Capgo のドキュメントでそのエラーを検索するか、サポートにお問い合わせください。

debug コマンドは、アップデートのダウンロードやインストールに関する問題を特定するのに非常に便利です。ログで期待するアップデートバージョンが見つかっているのに最終的に適用されていない場合は、ダウンロード以降のステップに絞ってトラブルシューティングしてください。

Native Logs を使ったデバッグ

Capgo debug コマンドに加えて、Android、iOS、Electron のネイティブログも、特にアップデートプロセスのネイティブ側で発生する問題の解決に役立つ情報を提供します。

Android ログ

Android ログを確認するには：

1. デバイスを接続するか、エミュレータを起動します
2. Android Studio を開き、「View > Tool Windows > Logcat」を選択します
3. Logcat ウィンドウで、上部のドロップダウンから自分のアプリのプロセスを選び、ログをそのプロセスだけに絞り込みます
4. 次の内容を含む行を探してください Capgo SDK のログを確認するには

または、以下の adb logcat コマンドを使用して、 Capgo ログをフィルタリングできます。

Capgo SDK は、アップデート中の以下のような主要なイベントをログに記録します：

• アップデートのチェックが開始されたとき
• アップデートが見つかった場合とそのバージョン
• アップデートのダウンロード開始時と完了時
• アップデートのインストールが実行されたとき
• Native Build のアップデート工程中に発生したエラー

ログに表示される可能性のある、Android 特有の一般的な問題には以下があります：

• ネットワーク接続の問題によるアップデートのダウンロード失敗
• アップデート用bundleの保存または読み込み時のファイル権限エラー
• アップデート用bundleのストレージ容量不足
• アップデート適用後のアプリ再起動の失敗

iOSのログ

iOSのログを確認するには：

1. デバイスを接続するか、シミュレータを起動します
2. Xcodeを開き、「Window > Devices and Simulators」に移動します
3. デバイスを選択し、「Open Console」をクリックします
4. コンソールの出力から、以下の文字列を含む行を探してください： Capgo SDK のログを見つけるために

また、以下を使用することも可能です： log stream ターミナルでコマンドを実行し、 Capgo でログをフィルタリングします。

Androidと同様に、Capgo SDK はiOS側の主要なイベントをログに記録します：

• アップデート確認の開始と結果
• ダウンロードの開始、進捗、完了
• インストール実行のトリガーと結果
• Native Buildのアップデートプロセス中のエラー

ログから特定できるiOS特有の問題には以下が含まれます：

• アップデートのダウンロード時におけるSSL証明書の問題
• App Transport Securityによるアップデートのダウンロードブロック
• アップデート用bundleの空き容量不足
• アップデート用bundleの展開または適用失敗

Electronのログ

Electronアプリの場合は、メインプロセスとレンダラープロセスの両方の出力を確認してください：

1. 通常の起動コマンドを使用して、ターミナルからElectronアプリを実行し（例： bun run electron:dev または bun run electron:serve）、起動時、アップデートのチェック、およびネットワークエラーに関するターミナルの出力を監視します。
2. レンダラーウィンドウでDevToolsを開き（View → Toggle Developer Tools）、アップデートのフローを再現しながら、コンソールログや失敗したネットワークリクエストを調査してください。
3. パッケージ化されたアプリの場合は、OSのログツールを使用してクラッシュや起動失敗を確認してください：
   • macOS: openを実行し、 Console.app アプリ名でフィルタリングします
   • Windows: 開く イベント ビューアー → Windows ログ → アプリケーション
   • Linux: デスクトップのログビューアーを使用するか、 journalctl アプリのプロセス用

アップデートのデバッグ時は、main-process と renderer-process 両方のログメッセージを比較してください。これにより、Electron のブートストラップの問題と Capgo のアップデートライフサイクルに関する問題を切り分けることができます。

プラットフォームを問わず、ネイティブログを使用すると、ネイティブ実装の詳細を含む、より低レイヤーなアップデートプロセスの状況を確認できます。これらは、Capgo の JavaScript レイヤー以外で発生している問題を特定する際に特に有用です。

厄介な live update の問題をトラブルシューティングする際は、Capgo のデバッグログとネイティブログの両方を取得して、何が起きているのかを包括的に把握することをお勧めします。これら2つのログを組み合わせることで、問題の特定と解決の可能性が最大限に高まります。

アップデートが適用されない場合

bundleをアップロードしたのにデバイスに反映されない場合は、以下を確認してください：

• アプリ内で正しく呼び出されているか確認してください： CapacitorUpdater.notifyAppReady() のドキュメントにある通り、アプリ内で code を呼び出しているか確認してください。 クイックスタート
• デバイスがインターネットに接続されているか、また Capgo のデバッグログにアップデートのダウンロードが表示されているか確認してください。
• アプリを完全に終了してから再起動してください。アップデートはアプリの起動時にのみ適用されます。
• アップデートの適用に失敗している可能性があるため、ネイティブログにエラーが出ていないか確認してください。

詳細は以下のドキュメントを参照してください： Live Updateのデプロイ アップデートプロセスの詳細については、こちらのガイドを確認してください。解決しない場合は、 npx @capgo/cli@latest app debug コマンドとネイティブログを使用して、詳細な状況を確認してください。

アップデート失敗時の主なエラーコード

ログに以下のようなバックエンドエラーが表示される場合は、 disable_auto_update_to_major, semver_error、または cannot_update_via_private_channel専用のガイドを参照してください：

• よくあるアップデートの問題

各codeの一般的な意味、発生原因、および解決方法について説明しています。

SDK のインストール

Capgo SDK のインストールで問題が発生している場合は、以下を確認してください：

• アプリがサポート対象の Capacitor バージョン（4.0以降）を使用していること
• 以下の手順に従ってください： クイックスタート SDK インストール後のアプリ同期を含め、手順を順番に進めてください

CI/CD 連携

CI/CD パイプラインから Capgo の upload をトリガーする際に問題がある場合:

• Capgo の認証トークンが正しく設定されているか再確認してください
• Web アセットのビルド後に upload コマンドを実行していることを確認してください
• upload コマンドで使用している channel 名が、対象の環境と一致しているか確認してください

詳細については、 CI/CD連携 その他のトラブルシューティングのヒントについては docs を参照してください。また、 npx @capgo/cli@latest app debug コマンドを使用して、CI/CD でトリガーされたアップデートがアプリに届いているか確認できます。

トラブルシューティングの次のステップ

使用している場合 トラブルシューティング ストレージとファイル処理を計画するには、以下と連携してください： @capgo/capacitor-data-storage-sqlite @capgo/capacitor-data-storage-sqlite の実装の詳細については、 @capgo/capacitor-data-storage-sqlite の使い方 「@capgo/capacitor-data-storage-sqliteの使用方法」におけるネイティブ機能について、 @capgo/capacitor-file @capgo/capacitor-file の実装の詳細については、 @capgo/capacitor-file の使い方 「@capgo/capacitor-file の使用」のネイティブ機能については、および @capgo/capacitor-uploader @capgo/capacitor-uploader. の実装の詳細については