追加のリソース

インストールステップとこのプラグインの全マークダウンガイドを含む設定のコピー用質問をコピーしてください。

Solutions to common issues when building native apps with 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キーが正しいことを確認する
- キーには 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 Portalで新しいものを作成
- 環境変数を再エンコードして更新

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

症状:

Xcodeがプロファイルに証明書を見つけることができない

解決策:

Appleから最新のプロファイルをダウンロード
- 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 分以内に有効期限切れになる JWT を拒否します。したがって、時刻のずれがわずかでも有効なキーを失敗させることができます
- On Windows, 設定 > 時間と言語 > 日付と時間 をクリック 現在の時間を同期
- On macOS, システム設定 > 一般 > 日付と時間 を有効
- On Linux, timedatectl status を確認し、必要に応じてNTPを有効
- Syncingが完了した後、Capgo ビルドまたは資格情報コマンドを再実行してください。
__CAPGO_KEEP_0__ 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 インストール失敗」

症状:

CocoaPodsのインストール中にビルドが失敗する
Podfileエラー

解決策:

Podfile.lockがコミットされていることを確認する
ターミナルウィンドウ
```
git status ios/App/Podfile.lock
```
ローカルでpod installをテストする
ターミナルウィンドウ
```
cd ios/App
pod install
```
互換性のないPodを確認する
- 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

「キーアリーサlias not found」

症状：

署名にエイリアスエラーが発生します

解決策:

キーストアのエイリアスの一覧を表示
ターミナルウィンドウ
```
keytool -list -keystore my-release-key.keystore
```
エイリアスが完全に一致することを確認
- エイリアスは大文字小文字区別
- KEYSTORE_KEY_ALIASに誤字がないか確認

正しいエイリアスをキーストアから使用

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

「Gradle ビルド失敗」

Symptoms:

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

Solutions:

ローカルでテストビルドを実行してみる
ターミナルウィンドウ
```
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で確認する

一般的な問題

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

症状:

ビルドステータスを確認できない
ジョブIDのエラー

解決策:

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

「プロジェクトの同期が失敗しました」

症状:

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

解決策:

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

ビルドは成功しましたが、出力は見られません

Symptoms:

ビルドは成功しましたが、ダウンロードリンクは表示されません。

Solutions:

ビルド設定を確認
- アーティファクトの保存場所の設定が正しくない場合
- サポートに連絡してください。アーティファクトのアクセスがビルドで利用できない場合
iOSのテストフライトの提出用
- App Store Connectを確認してください
- アップロード後5-30分程度で処理が完了する場合
AndroidのPlay Store用
- Play Console→テスト→内部テストを確認してください
- アップロード後数分程度で処理が完了する場合

環境切り替え後にビルドが成功したが、アーティファクトが間違っている場合

ビルドの状態は

ですが、IPA/AAB/APKは、直前にビルドしたブランチやフラバーと一致しません success IPA/AAB/APKは、直前にビルドしたブランチやフラーバーと一致しません。
Android AABが存在しない、またはRCとプロダクションのクレデンシャルを切り替えた後も間違っている --android-flavor
ビルドが不思議に早く終了するのは、署名設定や製品フラビアを変更した直後

原因: Capgoは アプリごとのビルドキャッシュを デフォルトで復元する (共有の一般的なキャッシュの場合、省略) cache_key RCとプロダクションが同じアプリIDを共有し、別々のキーを持っていない場合、復元は前の環境からコンパイルされた出力を再利用できます。

解決策:

環境ごとにキャッシュキーを使用する (継続的なRC/PROD Pipelinesの場合、推奨): ターミナルウィンドウ

# Production
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=prod \
  --android-flavor production

# Staging / RC
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=staging \
  --android-flavor staging

強制的に 1 回のクリーンビルド デバッグ時に:
ターミナルウィンドウ
```
bunx @capgo/cli@latest build request com.example.app --platform android --no-cache
```
API または Webhook 統合、パス cache_key (例えば "prod"）または設定 cache_enabled: false 詳細なオプションリファレンスは

ビルドキャッシュを参照してください。 Build cache

CI/CD関連の問題

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

症状:

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

解決策:

Bunを設定してください so bunx クリップボードにコピー
```
- uses: oven-sh/setup-bun@v2
```
CLIはCapgoの内部名です。 — bunx 必要なものはオンデマンドで取得するので、グローバルインストールは必要ありません:
```
- run: bunx @capgo/cli@latest build request com.example.app --platform android
```

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

症状:

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

解決策:

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

正しい構文を使用する

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: コミュニティに参加する
メール: サポート@capgo.app
ドキュメント: Capgo ドキュメント

既知の制限

現在の制限:

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

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

プレースキャンが私のビルドをブロックしました。

Capgoはローカルで プレースキャン を実行します。アップロードされる前に、報告された見つかりに修正するか、チェックIDを無視してください:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

全カタログを参照してください: 前処理チェック.

追加リソース

はじめに - 初期設定ガイド
構成オプション - CLI フラグ --cache-key and --no-cache
iOS ビルド - iOS固有の構成
Android ビルド - Android固有の構成
チェック前処理 - ビルド前処理のフルリストと無視フラグ
CLI リファレンス - コマンドの完全なドキュメント

追加のリソース

ビルド失敗

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

「10分以内にビルドタイムアウト」

利用ケースごとに制限を調整できます

「API キーが無効」または「未承認」

「アプリが見つかりません」または「このアプリに対する権限がありません」

iOS ビルドの問題

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

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

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

「Pod インストール失敗」

Android ビルド問題

「キーストアパスワードが不正です」

「キー アリーサlias not found」

「Gradle ビルド失敗」

アップロードに失敗しました

一般的な問題

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

「プロジェクトの同期が失敗しました」

ビルドは成功しましたが、出力は見られません

環境切り替え後にビルドが成功したが、アーティファクトが間違っている場合

CI/CD関連の問題

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

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

さらにヘルプを取得する

詳細ログを有効にする

ビルド情報を収集する

サポートに連絡する

既知の制限

プレースキャンが私のビルドをブロックしました。

追加リソース

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

「キーアリーサlias not found」