トラブルシューティング

インストール手順とこのプラグインの全マークダウンガイドを含むセットアップ用の質問をコピーできます。

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

ビルドエラー

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

症状：

アップロード中にプロジェクトが失敗する
60秒以内にタイムアウトエラーが発生する

解決策：

インターネット接続を確認する
ターミナル画面
```
# Test connection to Capgo
curl -I https://api.capgo.app
```
プロジェクトサイズを削減する
- 確保する node_modules/ アップロードされていない (自動除外されるはず)
- プロジェクト内の大きなファイルを確認する：
ターミナル画面
```
find . -type f -size +10M
```
アップロード URL の有効期限を確認
- アップロード URL は 1 時間で有効期限切れになります
- 有効期限切れの URL エラーが発生した場合は、ビルドコマンドを再実行してください

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

「ビルド時間制限は 10 分後」

症状：
状態は表示 timeout

ソリューション：

依存関係を最適化
- 不要なnpmパッケージを削除
- 使用 npm prune --production ビルドする前に
ビルド中にネットワーク問題を確認
- ビルド中に依存関係が大きなファイルをダウンロードする場合があります
- ロックファイルを使用したキャッシュを考慮

ネイティブ依存関係を確認

# iOS - check Podfile for heavy dependencies
cat ios/App/Podfile

# Android - check build.gradle
cat android/app/build.gradle

サポートに連絡
- アプリが正当にさらに時間が必要な場合
- 特定の用途のために制限を調整できます

認証問題

「API キーが無効」または「認証されていません」

症状：

認証エラーによりビルドが即座に失敗します
401または403エラー

解決策：

API キーが正しいことを確認してください
ターミナル画面
```
# Test with a simple command
bunx @capgo/cli@latest app list
```
APIキーの権限を確認
- __CAPGO_KEEP_0__キーには write または all 権限
- CapgoダッシュボードのAPIキーよりも確認

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)

再認証
ターミナル画面
```
bunx @capgo/cli@latest login
```

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

症状：

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

解決策：

アプリが登録されていることを確認してください
ターミナル画面
```
bunx @capgo/cli@latest app list
```
アプリIDが一致していることを確認してください
- 確認 capacitor.config.json appId
- 正しいアプリIDを使用するコマンドを確認する
組織へのアクセスを確認する
- 正しい組織にいることを確認する
- API キーはアプリの組織にアクセスできる必要があります

iOS ビルド問題

「Code 署名が失敗しました」

症状:

ビルドが code 署名フェーズで失敗する
証明書またはプロファイルに関する Xcode のエラー

解決策:

証明書のタイプがビルドのタイプと一致することを確認する
- 開発用ビルドには開発用証明書が必要
- App Store用ビルドには配布用証明書が必要

証明書とプロファイルが一致することを確認する

# 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

プロビジョニングプロファイルが有効であることを確認する
- 有効期限を確認する
- App IDが含まれていることを確認する
- 証明書が含まれていることを確認する
クレデンシャルを再生成する
- 古い証明書/プロファイルを削除する
- Apple Developer ポータルで新しいものを作成する
- 環境変数を再エンコードして更新する

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

症状:

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

解決策:

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

プロファイルに証明書が含まれていることを確認する

# Extract profile
echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision

# View profile contents
security cms -D -i profile.mobileprovision

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

App Store Connect の認証が失敗しました

症状：

テストフライトへのアップロードが失敗
API キーエラー

解決策：

API キー資格情報を確認する
- APPLE_KEY_ID (10文字であることを確認する)
- APPLE_ISSUER_ID (UUID形式であることを確認する)
- APPLE_KEY_CONTENT が正しく base64 でエンコードされていることを確認する
コンピューター時計を同期する
- App Store Connect の認証では、ローカルシステムの時刻から短期間の JWT を生成します
- Apple は、20 分以内に有効期限切れになるトークンを拒否します。時刻のずれが小さくても、有効なキーでもある場合でも、失敗する可能性があります
- Windows の場合、 設定 > 時刻と言語 > 日付と時刻 をクリックして 今すぐ同期する
- macOS の場合、 システム設定 > 一般 > 日付 & 時間 自動時刻設定を有効にしてください
- Linuxでは、 timedatectl status 必要に応じてNTPを有効にしてください
- 同期後、再度Capgoビルドまたは資格情報コマンドを実行してください
Appleの APIリクエスト用トークン生成ドキュメントを参照してください。App Store Connectトークン有効期限ルール

APIキーのローカルテスト

# Decode key
echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8

# Test with fastlane (if installed)
fastlane pilot list

APIキーの権限を確認
- 開発者ロールまたはそれ以上の権限が必要
- App Store Connect -> ユーザーとアクセス -> キーで確認
キーが取り消されていないことを確認
- App Store Connectで確認
- 必要に応じて新しいキーを生成

”Pod install failed”

症状:

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

解決策:

Podfile.lockがコミットされていることを確認
ターミナルウィンドウ
```
git status ios/App/Podfile.lock
```
ローカルでテストする
ターミナルウィンドウ
```
cd ios/App
pod install
```
不相容なポッドを確認する
- Podfileのバージョンコンフリクトを確認する
- iOSのデプロイメントターゲットをサポートするすべてのポッドを確認する

キャッシュをクリアする

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

Androidビルドの問題

キーストアパスワードが不正

症状:

署名中にビルドが失敗
Gradle がキーストアに関するエラーを出します

解決策:

キーストアパスワードを確認

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

環境変数を確認

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

Base64エンコードを検証する

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

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

症状：

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

解決策：

キーストアのアリーサイズの一覧
ターミナル画面
```
keytool -list -keystore my-release-key.keystore
```
__CAPGO_KEEP_0__を正確に検証します
- __CAPGO_KEEP_0__は大文字小文字区別
- KEYSTORE_KEY_ALIASに誤字がないか確認

keystoreから正しい__CAPGO_KEEP_0__を使用

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

Gradleビルド失敗

症状:

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

解決策:

ローカルでビルドする前にテストしてください
ターミナル画面
```
cd android
./gradlew clean
./gradlew assembleRelease
```
依存関係が不足しているかどうか確認する
- build.gradleファイルを確認する
- すべてのプラグインが依存関係にリストされていることを確認する

Gradleのバージョン互換性を確認する

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

Gradleのキャッシュをクリアする
ターミナル画面
```
cd android
./gradlew clean
rm -rf .gradle build
```

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

症状：

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

解決策：

サービスアカウントの JSON を確認する
ターミナルウィンドウ
```
# Decode and check format
echo $PLAY_CONFIG_JSON | base64 -d | jq .
```
サービスアカウントの権限を確認する
- Play Console → 設定 → API アクセスに移動する
- サービスアカウントがアプリにアクセスできることを確認する
- リリーステストトラックスへの許可を付与する
Play Consoleでアプリが設定されていることを確認する
- Play Consoleでアプリが作成されていることを確認する
- 少なくとも1つのAPKを手動でアップロードする必要がある
APIが有効になっていることを確認する
- Google Play Developer APIが有効になっていることを確認する
- Google Cloud Consoleで確認する

一般的な問題

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

protectedTokens

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

解決策:

しばらく待ってから再試行してください
- ビルドジョブは数秒で初期化されることがあります
ジョブIDが正しいことを確認してください
- 初回ビルドのレスポンスからジョブIDを確認してください
ビルドが期限切れではないことを確認してください
- ビルドデータは24時間利用可能です

”Project sync failed”

症状:

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

解決策:

ローカルで Capacitor を同步実行する
ターミナル画面
```
bunx cap sync
```
すべてのネイティブファイルがコミットされていることを確認する
ターミナル画面
```
git status ios/ android/
```
gitignoreされたネイティブファイルを確認する
- .gitignoreを確認する
- 重要な設定ファイルがgitignoreされていないことを確認する

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

症状:

ビルドは成功していますが、ダウンロードリンクが見られません

解決策:

ビルド設定を確認してください
- アーティファクトの保存設定が有効になっていません
- アーティファクトのアクセスが不可な場合は、サポートに連絡してください
iOSのテストフライトの投稿の場合
- App Store Connectを確認してください
- アップロード後、5-30分程度の処理時間がかかります
AndroidのPlay Storeの投稿の場合
- Play Console → テスト → 内部テストを確認
- 処理には数分かかる場合があります

CI/CD固有の問題

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

症状：

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

解決策：

まずBunを設定し その後 bunx 利用可能です:
```
- uses: oven-sh/setup-bun@v2
```
CLIを実行してください — bunx 必要なものはすべてインストールする必要はありません。
```
- run: bunx @capgo/cli@latest build request com.example.app --platform android
```

GitHub Actions: “Secrets not found”

症状:

ビルド時環境変数が空です

解決策:

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

正しい構文を使用してください

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

秘密の名前が一致することを確認してください
- 名前は大文字小文字区別されています
- 秘密の参照に誤字がないことを確認してください

さらにヘルプを取得する

詳細なログを有効にする

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

ビルド情報を収集する

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

使用したビルドコマンド

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

エラーメッセージ (フルアウトプット)
ジョブID (ビルド出力から)
ビルドログ (フルターミナル出力のコピー)

環境情報

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

サポートに連絡

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

既知の制限事項

Current limitations:

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

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

追加リソース

Capgo の始め方 - 初期設定ガイド
iOS ビルド - iOS固有の設定
Android ビルド - Android用の構成
CLI リファレンス - 完全なコマンドドキュメント

トラブルシューティング

ビルドエラー

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

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

認証問題

「API キーが無効」または「認証されていません」

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

iOS ビルド問題

「Code 署名が失敗しました」

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

App Store Connect の認証が失敗しました

”Pod install failed”

Androidビルドの問題

キーストアパスワードが不正

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

Gradleビルド失敗

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

一般的な問題

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

”Project sync failed”

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

CI/CD固有の問題

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

GitHub Actions: “Secrets not found”

さらにヘルプを取得する

詳細なログを有効にする

ビルド情報を収集する

サポートに連絡

既知の制限事項

追加リソース

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

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

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