トラブルシューティング

Capgo Cloud Buildでネイティブアプリをビルドする際に発生する一般的な問題の解決策です。

ビルド失敗

アップロード失敗または接続タイムアウト

症状：

• プロジェクトアップロード中にビルドが失敗します
• 60秒後にタイムアウトエラーが発生します

解決策:

1. インターネット接続を確認してください

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. プロジェクトサイズを削減する

   • 確保する node_modules/ アップロードされていない (自動除外されるべき)
   • プロジェクト内の大きなファイルを確認してください:

   find . -type f -size +10M

3. __CAPGO_KEEP_0__の有効期限を確認

   • 1時間後には__CAPGO_KEEP_0__が有効期限切れになります
   • __CAPGO_KEEP_0__の有効期限切れエラーが発生した場合は、ビルドコマンドを再実行してください

ヒント

非常に大きなプロジェクトでは、ビルド時間制限に達する可能性があります（参照 知名度のある制限事項). Contact support for enterprise options.

”Build timeout after 10 minutes”

エンタープライズオプションの場合は、サポートに連絡してください。

• ”ビルド時間制限 10 分後”のセクションのタイトルは “”ビルド時間制限 10 分後””です。
• Status shows timeout

Solutions:

1. 依存関係を最適化する

   • 使用されていない npm パッケージを削除する
   • Capacitor を使用する npm prune --production ビルドする前に

2. ネットワーク問題をビルド中に検出する

   • ビルド中に大きなファイルをダウンロードする可能性のある依存関係がある
   • ロックファイルを使用した前キャッシュを検討する

3. ネイティブ依存関係を確認する

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. サポートに連絡してください

   • __CAPGO_KEEP_0__ キーが必要な場合、正当な理由がある場合
   • 特定のケースで制限を調整できます

認証問題

”API key invalid” or “Unauthorized”

セクション「 または「認証されていません」

• 症状:
• ビルドが認証エラーで即座に失敗します

401または403エラー

1. Verify API key is correct

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. APIキーの権限を確認

   • __CAPGO_KEEP_0__キーには write または all 権限
   • CapgoダッシュボードのAPIキーよりも確認

3. APIキーが正しく読み込まれていることを確認

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. 再認証

   bunx @capgo/cli@latest login

アプリが見つかりませんか、またはアプリへのアクセス権限がありませんか

症状：

• 認証は正常に動作していますが、アプリ固有のエラーが発生しています

解決策：

1. アプリが登録されていることを確認してください

   bunx @capgo/cli@latest app list

2. アプリIDが一致していることを確認してください

   • 確認 capacitor.config.json appId
   • 正しいアプリIDを使用するコマンドを確認する

3. 組織へのアクセスを確認する

   • 正しい組織にいることを確認する
   • API キーはアプリの組織にアクセスできる必要があります

iOS ビルド問題

「Code シグニング失敗」

症状:

• ビルドがcode シグニングフェーズで失敗する
• Xcode から証明書またはプロファイルに関するエラーが発生する

解決策:

1. 証明書のタイプがビルドタイプと一致していることを確認

   • 開発用ビルドには開発用証明書が必要
   • App Store用ビルドには配布用証明書が必要

2. 証明書とプロファイルが一致していることを確認

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. プロビジョニングプロファイルが有効であることを確認

   • 有効期限を確認
   • App IDが含まれていることを確認
   • 証明書が含まれていることを確認

4. クレデンシャルを再生成

   • 古い証明書/プロファイルを削除
   • Apple Developer ポータルで新しいものを作成する
   • 環境変数を再エンコードして更新する

署名証明書が含まれていないプロビジョニング プロファイル”

症状：

• プロファイル内で証明書が見つからない

解決策：

1. Apple Developer ポータルから最新のプロファイルをダウンロードする

   • Apple Developer → 証明書、ID、プロファイルに移動する
   • プロビジョニング プロファイルをダウンロードする
   • プロファイルに自分の証明書が含まれていることを確認する

2. プロファイル内で証明書が有効であることを確認する

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. 正しい証明書でプロファイルを再作成

   • Apple Developer ポータルでプロファイルを編集
   • 配布用証明書が選択されていることを確認
   • ダウンロードして再エンコード

”App Store Connect authentication failed”

Symptoms:

• App Store Connect の認証に失敗しました”
• API key errors

テストフライトへのアップロードに失敗する場合に発生する症状です。

1. API キー資格情報を確認する

   • APPLE_KEY_ID (10文字でなければなりません) を確認する
   • APPLE_ISSUER_ID (UUID形式でなければなりません) を確認する
   • APPLE_KEY_CONTENT が正しく base64 でエンコードされていることを確認する

2. コンピュータの時計を同期する

   • App Store Connect の認証では、ローカルシステムの時刻から生成された短期間の JWT を使用します
   • Apple は、20 分以内に有効期限切れになるトークンを拒否します。したがって、時計のズレが小さくても、有効なキーでもある場合でも、認証が失敗することがあります。
   • Windows の場合、 設定 > 時刻と言語 > 日付と時刻 をクリックして 今すぐ同期する
   • macOS の場合、 システム設定 > 一般 > 日付と時刻 自動時刻設定を有効にしてください
   • Linuxでは、 timedatectl status 必要に応じてNTPを有効にしてください
   • 同期後、Capgoのビルドまたは資格情報コマンドを再実行してください

   Appleの APIの要求用にトークンを生成する App Store Connectのトークン有効期間ルールの詳細は、

3. APIキーのローカルテスト

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. APIキーの権限を確認

   • 開発者ロールまたはそれ以上の権限が必要
   • App Store Connect -> ユーザーとアクセス -> キーで確認

5. キーが取り消されていないことを確認

   • App Store Connectで確認
   • 必要に応じて新しいキーを生成

”Pod install failed”

症状:

• ココアポッドのインストール中にビルドが失敗
• Podfileエラー

解決策:

1. Podfile.lockがコミットされていることを確認

   git status ios/App/Podfile.lock

2. ローカルでテストポッドインストール

   cd ios/App
   pod install

3. 不相容なポッドをチェック

   • Podfileのバージョンコンフリクトを確認
   • iOSのデプロイメントターゲットをサポートするすべてのポッドを確認

4. ポッドキャッシュをクリア

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Androidビルド問題

Keystore パスワードが不正です

症状：

• 署名中にビルドが失敗
• Gradle から Keystore についてのエラー

解決策：

1. Keystore パスワードを確認

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. 環境変数を確認

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Base64エンコードを検証する

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

「キー アリーサーが見つかりません」

症状：

• アリーサー エラーで署名が失敗する

解決策：

1. キーストアのアリーサーの一覧

   keytool -list -keystore my-release-key.keystore

2. Aliasが正確に一致することを確認

   • Aliasは大文字小文字区別
   • KEYSTORE_KEY_ALIASに誤字がないか確認

3. キーストアから正しいAliasを使用

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

”Gradleビルド失敗”

症状：

• 一般的なGradleエラー
• コンパイルまたは依存関係の問題

解決策：

1. ローカルでビルドをテストする

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 依存関係が不足しているかどうか確認

   • build.gradleファイルを確認
   • すべてのプラグインが依存関係にリストされているかどうか確認

3. Gradleのバージョン互換性を確認

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Gradleのキャッシュをクリア

   cd android
   ./gradlew clean
   rm -rf .gradle build

”アプリストアのアップロード失敗””

症状:

• ビルドは成功しますが、アップロードは失敗します
• サービスアカウントのエラー

解決策:

1. サービスアカウントのJSONを確認

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. サービスアカウントの権限を確認

   • Play Console → 設定 → API アクセスに移動
   • サービスアカウントがアプリにアクセスできることを確認
   • リリーステストトラックへの許可を付与する

3. アプリがPlay Consoleに設定されていることを確認する

   • Play Consoleにアプリが作成されていることを確認する
   • Play Consoleにアプリを作成する必要がある

4. Check API is enabled

   • APIが有効になっていることを確認する
   • Google Play Developer __CAPGO_KEEP_0__が有効になっていることを確認する

Google Cloud Consoleで確認する

「ジョブが見つかりません」または「ビルドステータスが利用できません」

症状：

• ビルドステータスを確認できません
• ジョブIDのエラー

解決策：

1. しばらく待ってから再試行

   • ビルドジョブは数秒間で初期化されることがあります

2. ジョブIDが正しいかどうか確認してください

   • 初回ビルドのレスポンスからジョブIDを確認してください

3. ビルドが期限切れではないかどうか確認してください

   • ビルドデータは24時間利用可能です

プロジェクトの同期に失敗しました

症状：

• コンパイルが開始される前にビルドが失敗する
• ファイルが見つからないエラー

解決策:

1. ローカルで Capacitor を同步実行する

   bunx cap sync

2. すべてのネイティブファイルがコミットされていることを確認する

   git status ios/ android/

3. gitignored されているネイティブファイルを確認する

   • .gitignore を確認する
   • 重要な設定ファイルが無視されていないことを確認する

ビルド成功ですが、出力が見られません

症状:

• ビルドは成功していますが、ダウンロードリンクが表示されません

解決策:

1. ビルド設定を確認してください

   • アーティファクトの保存設定が正しくない可能性があります
   • アーティファクトのアクセスが不可な場合は、サポートに連絡してください

2. iOSのテストフライトの投稿の場合

   • App Store Connectを確認してください
   • アップロード後、5-30分程度の処理時間がかかる場合があります

3. AndroidのPlay Storeの投稿の場合

   • Play Console → テスト → 内部テストを確認してください
   • 処理には数分かかる場合があります

CI/CD固有の問題

GitHub アクション: 「コマンドが見つかりません」

症状:

• bunx @capgo/cli@latest … CIで「コマンドが見つかりません」というエラーが発生します

解決策:

1. Bun を設定してください したがって bunx 利用可能です:

   - uses: oven-sh/setup-bun@v2

2. 次に、CLIを実行してください — bunx __CAPGO_KEEP_0__は必要なものだけをオンデマンドで取得するため、グローバルインストールは必要ありません:

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub アクション: “シークレットが見つかりません”

症状:

• ビルド中の環境変数が空です

解決策:

1. シークレットが設定されていることを確認してください

   • リポジトリの設定 → シークレットと変数 → アクションに移動してください
   • 必要なすべてのシークレットを追加してください

2. __CAPGO_KEEP_0__を正しく記述する

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. 秘密名が一致するか確認する

   • 名前は大文字小文字が区別される
   • シークレット参照に誤字がない

さらにヘルプを取得する

詳細ログを有効にする

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

ビルド情報を収集する

サポートに連絡する際には、以下を含めてください。

1. 使用したビルドコマンド

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. エラーメッセージ (フル出力)

3. ジョブID (ビルド出力から)

4. ビルドログ (フルターミナル出力コピー)

5. 環境情報

   node --version
   npm --version
   bunx @capgo/cli@latest --version

サポートに連絡

• Discord: コミュニティに参加
• メール: support@capgo.app
• ドキュメント: Capgo ドキュメント

既知の制限事項

現在の制限:

• 最大ビルド時間: 10 分
• 最大アップロードサイズ: ~500MB
• iOS ビルドには 24 時間の Mac のレンタルが必要です。Mac でビルドすると、最適な使用を確保するためにキューに追加されます。
• ビルドアーティファクトのダウンロードの可用性は、ビルドの目的地とアーティファクトのストレージの構成に依存します。

これらの制限は、フィードバックに基づいて調整される可能性があります。

追加リソース

• Getting Started - 初期設定ガイド
• iOS ビルド - iOS固有の設定
• Android ビルド - Android用の設定
• CLI リファレンス - 完全なコマンドドキュメント