トラブルシューティング

このプラグインのインストール手順とフルマークダウンガイドのセットアッププロンプトをコピーする

Here are some common issues you might encounter while using Capgo and how to resolve them.

🚀 専門家の助けが必要ですか。

Stuck with a complex issue? Our expert team is here to help! Get personalized support, code reviews, and custom solutions tailored to your specific needs.

プロフェッショナルサポートを取得

アップロード失敗

アップロードが失敗した場合、確認してください:

Capgoのダッシュボードに登録されているアプリIDが capacitor.config.ts matches your app in the Capgo dashboard
You’re running the upload command from the root of your Capacitor project
Webアセットがビルドされ最新の状態であることを確認してください。

高度なアップロードオプション

Capgo CLIは、一般的なアップロード問題に役立つ追加のフラグを提供します:

--tus: __CAPGO_KEEP_0__が使用するプロトコル tus再開可能なアップロードプロトコル大きなバンドルやネットワーク接続が悪い場合に信頼性の高いアップロードを行うために使用します。バンドルが10MBを超えている場合やネットワーク接続が悪い場合、__CAPGO_KEEP_0__を使用してみてください。 --tus:
ターミナル画面
```
npx @capgo/cli@latest bundle upload --tus
```
--package-json 、 --node-modules: Capgoがアプリのrootを探す場所を指定します。 package.json rootの場所を__CAPGO_KEEP_0__に教えます。 node_modules アプリが標準的な構造を使用していない場合、例えばモノレポやnpmワークスペースを使用している場合、rootのパスを指定してください。 package.json そして --node_modules path:
ターミナルウィンドウ
```
npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules
```
Capgoにはこの情報が必要です。アプリの依存関係を正しくバンドルするため。

必要に応じて他のオプションと組み合わせることができます。 --channel __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ドキュメント Capgo CLI docs アップロードの問題が解決しない場合、__CAPGO_KEEP_0__サポートまでご連絡ください。

さらに支援を受けることができます。 Capgo __CAPGO_KEEP_1__

アップデートのデバッグ

ライブアップデートで問題が発生している場合、Capgo デバッグコマンドはトラブルシューティングに役立つツールです。使用方法は次のとおりです。

プロジェクトディレクトリで次のコマンドを実行します。
ターミナル画面
```
npx @capgo/cli@latest app debug
```
デバイスまたはエミュレータでアプリを起動し、更新をトリガーするアクションを実行してください (例: アップロードした新しいバンドルをアップロードした後、アプリを再起動します)。
デバッグコマンドの出力を確認してください。アップデートプロセスに関する情報をログします。次の情報が含まれます。
- アプリがアップデートをチェックする
- アップデートが見つかった場合とそのバージョン
- アップデートのダウンロードとインストールの進行状況
- アップデートプロセス中に発生したエラー
問題の発生箇所を特定するには、デバッグログを使用してください。例えば:
- アップデートが見つからない場合は、バンドルが正常にアップロードされたかどうか、またアプリが正しいチャンネルを使用しているかどうかを確認してください。
- アップデートがダウンロードされるがインストールされない場合は、 CapacitorUpdater.notifyAppReady() を呼び出して、そしてアプリが完全に閉じて再起動されていることを確認してください。
- エラーメッセージが表示される場合は、Capgo ドキュメントでその特定のエラーを調べたり、サポートに問い合わせたりしてください。

デバッグコマンドは、特にアップデートのダウンロードとインストールプロセスに関連する問題を特定するのにとても役立ちます。ログが期待どおりのアップデートバージョンが見つかったが最終的に適用されなかった場合は、ダウンロード後のステップに焦点を当ててトラブルシューティングを進めてください。

ネイティブログを使用したデバッグ

In addition to the Capgo debug command, the native logs on Android, iOS, and Electron can provide valuable troubleshooting information, especially for issues on the native side of the update process.

Android ログ

Android ログにアクセスするには:

デバイスを接続したりエミュレータを起動したりしてください
Android Studioを開いて「ビュー > ツールウィンドウ > Logcat」を選択してください
Logcatウィンドウで、ログをあなたのアプリのプロセスだけに絞り込むには、上部のドロップダウンから選択してください
あなたのアプリのログを見つけるには、以下の行を探してください Capgo SDK ログを見つけるには、以下の行を探してください

代わりに、以下のコマンドを使用して、__CAPGO_KEEP_0__ ログをフィルタリングできます adb logcat コマンドと、以下の文字列を使用してログをフィルタリングできます Capgo __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ は、更新プロセス中にキーエベントをログします。たとえば:

The Capgo SDK will log key events during the update process, such as:

更新が見つかり、どのバージョンであるか
更新ダウンロードが開始され、完了したとき
更新ダウンロードが完了したとき
When the update installation is triggered
native update の実行中に発生するエラー

ログに表示される Android固有の問題の例:

更新ダウンロードを阻害するネットワーク接続問題
更新パッケージを保存または読み込む際のファイルパーミッションエラー
更新パッケージの保存に十分なストレージスペースが確保されていない
更新がインストールされた後、再起動に失敗する

iOSログ

iOSログにアクセスするには:

デバイスを接続するかシミュレータを起動する
Xcodeを開き、「Window > Devices and Simulators」に移動する
デバイスを選択し、「コンソールを開く」をクリックしてください。
コンソール出力で、__CAPGO_KEEP_0__ を含む行を探してください。 Capgo SDK ログを探すには、以下のコマンドを使用してください。

ターミナルで以下のコマンドを実行し、__CAPGO_KEEP_0__ を含むログをフィルタリングしてください。 log stream iOS側の重要なイベントをログするには、__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ を使用します。 Capgo iOS側の重要なイベントをログするには、__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ を使用します。

Similar to Android, the Capgo SDK will log key iOS-side events:

ダウンロードの開始、進行、完了
インストールのトリガーと結果
ネイティブアップデートプロセス中のエラー
iOS固有の問題は、以下のログで確認できます。

iOS固有の問題は、以下のログで確認できます。

ダウンロードアップデートの際のSSL証明書問題
アップデートダウンロードをブロックするアプリケーションTransportセキュリティ
アップデートパッケージのストレージスペースが不足している
アップデートパッケージの適切な抽出または適用に失敗

Electronログ

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

ターミナルからElectronアプリを実行し、通常の起動コマンドを使用して (例えば、 bun run electron:dev または bun run electron:serve)、起動、更新チェック、ネットワークエラーのためのターミナル出力を確認してください。
レンダラーウィンドウでDevToolsを開き (View → Toggle Developer Tools)、アップデートフローを再現する際にコンソールログと失敗したネットワークリクエストを検査してください。
パッケージアプリ用に、OSのログツールを使用してクラッシュや起動失敗を確認してください:
- macOS：開く Console.app アプリ名で絞り込む
- Windows：開く イベントビューアー → Windows ログ → アプリケーション
- Linux：デスクトップログビューアーを使用してアプリケーションプロセスを表示 journalctl デバッグ更新時は、メインプロセスとレンダラープロセスのログから両方のメッセージを比較して、Electron の初期化問題と __CAPGO_KEEP_0__ の更新ライフサイクル問題を区別する必要があります。.

When debugging updates, compare messages from both main-process and renderer-process logs to separate Electron bootstrap issues from Capgo update lifecycle issues.

プラットフォームを横断するnativeログは、native実装に関するより低レベルのビューを提供し、より詳細な情報を提供します。特に、Capgo JavaScriptレイヤー外部で発生する問題を特定するのに役立ちます。

トラブルシューティングの際に、難しいライブアップデートの問題に直面した場合、Capgo debugログとnativeログを両方キャプチャすることをお勧めします。これにより、起こっていることの包括的な理解が得られます。

Updates not applying

Section titled “Updates not applying”

更新が適用されない CapacitorUpdater.notifyAppReady() in your app code as shown in the アップロードしたバンドルがデバイス上で表示されない場合:
Check that your device is connected to the internet and the Capgo debug logs show the update was downloaded
__CAPGO_KEEP_0__をアプリ内で呼び出していることを確認してください。
quickstart

__CAPGO_KEEP_0__のクイックスタートを参照してください。 deploying live updates guide for more details on the update process. If you’re still stuck, use the npx @capgo/cli@latest app debug command and native logs to get more visibility into what’s happening.

Common update failure codes

If your logs show backend errors such as disable_auto_update_to_major, semver_error, or cannot_update_via_private_channel, use the dedicated guide:

Common Update Problems

It explains what each common code means, why it happens, and how to fix it.

SDK Installation

インストールに問題がある場合は、Capgo SDK が正しくインストールされていることを確認してください。

Capacitor のサポートバージョン (4.0 以上) を使用していることを確認してください。
問題が解決しない場合は、次のことを確認してください。クイックスタート SDK をインストールした後、アプリを同步するなど、順番に実行した "クイックスタート" のステップを確認してください。

CI/CD統合

CI/CDパイプラインから Capgo のアップロードをトリガーする問題については、

Capgo の認証トークンが正しく設定されていることを確認してください。
__CAPGO_KEEP_0__ のアップロードコマンドを実行する前に、ウェブアセットがビルドされていることを確認してください。
__CAPGO_KEEP_0__ のアップロードコマンドが、ターゲット環境の正しいチャンネル名を使用していることを確認してください。

詳細は CI/CD統合 docsでトラブルシューティングのヒントをもっと見つけることができます。また、CI/CDをトリガーする更新がアプリケーションに受け取られているかどうかを確認するには、 npx @capgo/cli@latest app debug コマンドを使用できます。