Risolvere Problemi

Soluzioni per i problemi comuni quando si costruiscono applicazioni native con Capgo Cloud Build.

Fallimenti di costruzione

”Caricamento fallito” o “Timeout di connessione”

Sintomi:

• Il caricamento del progetto fallisce durante la costruzione
• Error di timeout dopo 60 secondi

Soluzioni:

1. Controlla la tua connessione internet

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

2. Riduci la dimensione del progetto

   • Assicurati node_modules/ non viene caricato (dovrebbe essere escluso automaticamente)
   • Controlla la presenza di file grandi nel tuo progetto:

   find . -type f -size +10M

3. Controlla la scadenza dell'URL di caricamento

   • Gli URL di caricamento scadono dopo 1 ora
   • Se ottieni un errore di URL scaduto, ripeti il comando di build

Suggerimento

I progetti molto grandi possono superare il limite di tempo di build (vedi Limitazioni noteContatta il supporto per opzioni aziendali.

Timeout di costruzione dopo 10 minuti

Sintomi:

• La costruzione supera il tempo massimo consentito
• Lo stato mostra timeout

Soluzioni:

1. Optimizza le dipendenze

   • Elimina i pacchetti npm non utilizzati
   • Usa npm prune --production prima di costruire

2. Controlla le problematiche di rete durante la costruzione

   • Alcune dipendenze possono scaricare file di grandi dimensioni durante la costruzione
   • Considerare il pre-caching con un file di blocco

3. Recensisci le dipendenze native

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

4. Contatta il supporto

   • Se il tuo app ha effettivamente bisogno di più tempo
   • Potremmo regolare i limiti per casi d'uso specifici

Issue di autenticazione

"API chiave non valida" o "Non autorizzato"

Sintomi:

• Costruisce fallisce immediatamente con errore di autenticazione
• 401 o 403 errori

Soluzioni:

1. Verifica che la chiave API sia corretta

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

2. Controlla i permessi della chiave API

   • La chiave deve avere write o all Controlla nel pannello di controllo __CAPGO_KEEP_0__ sotto __CAPGO_KEEP_1__ Chiavi
   • Check in Capgo dashboard under API Keys

3. Ensure API key is being read

   # 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. Riaccredita

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

Sintomi:

• L'autenticazione funziona ma si verifica un errore specifico dell'app

Soluzioni:

1. Verifica che l'app sia registrata

   bunx @capgo/cli@latest app list

2. Verifica che l'ID dell'app corrisponda

   • Verifica capacitor.config.json ID dell'app
   • Assicurati che il comando utilizzi l'ID dell'app corretto

3. Verifica l'accesso all'organizzazione

   • Assicurati di essere nell'organizzazione corretta
   • La chiave API deve avere accesso all'organizzazione dell'app

Issue di costruzione per iOS

“La firma di Code è fallita”

Sintomi:

• Il build fallisce durante la fase di firma code
• Errori di Xcode relativi a certificati o profili

Soluzioni:

1. Verifica che il tipo di certificato corrisponda al tipo di build

   • I build di sviluppo richiedono certificati di sviluppo
   • I build per l'App Store richiedono certificati di distribuzione

2. Verifica che il certificato e il profilo corrispondano

   # 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. Assicurati che il profilo di provisioning sia valido

   • Verifica la data di scadenza
   • Verifica che includa il tuo ID App
   • Conferma che includa il certificato

4. Regenera le credenziali

   • Cancella il vecchio certificato/profilo
   • Creane di nuovi nel portale dello sviluppatore Apple
   • Riaccodifica e aggiorna le variabili di ambiente

”Il profilo di provisioning non include il certificato di firma”

Sintomi:

• Xcode non riesce a trovare il certificato nel profilo

Soluzioni:

1. Scarica il profilo più recente da Apple

   • Vai a Apple Developer → Certificati, ID e Profili
   • Scarica il profilo di provisioning
   • Assicurati che contenga il tuo certificato

2. Verifica che il certificato sia presente nel profilo

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

3. Ricrea il profilo con il certificato corretto

   • Nel portale di Apple Developer, modifica il profilo
   • Assicurati di aver selezionato il tuo certificato di distribuzione
   • Scarica e ricodifica

”Autenticazione App Store Connect fallita”

Sintomi:

• La pubblicazione su TestFlight fallisce
• API chiave errori

Soluzioni:

1. Verifica le credenziali della chiave API

   • Controlla APPLE_KEY_ID (dovrebbe essere 10 caratteri)
   • Controlla APPLE_ISSUER_ID (dovrebbe essere nel formato UUID)
   • Verifica che APPLE_KEY_CONTENT sia correttamente codificato in base64

2. Sincronizza l'orologio del computer

   • L'autenticazione di App Store Connect utilizza JWT a breve scadenza generati dal tempo del sistema locale
   • Apple rifiuta i token che scadono dopo più di 20 minuti, quindi anche piccoli disallineamenti dell'orologio possono rendere una chiave altrimenti valida non valida
   • Su Windows, apri Impostazioni > Tempo e lingua > Data e ora e clicca Clicca su "Sincronizza ora"
   • Su macOS, apri Impostazioni del sistema > Generale > Data e ora e abilita l'orologio automatico
   • Su Linux, controlla timedatectl status e abilita NTP se necessario
   • Dopo aver sincronizzato, esegui nuovamente il comando di costruzione o di credenziali Capgo

   Vedi la documentazione di Apple su Generazione di token per le richieste API la regola di durata del token per l'App Store Connect.

3. Testa la chiave API localmente

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

4. Controlla le autorizzazioni della chiave API

   • La chiave richiede il ruolo 'Developer' o superiore
   • Verifica in App Store Connect -> Utenti e accessi -> Chiavi

5. Assicurati che la chiave non sia revocata

   • Controlla in App Store Connect
   • Genera una nuova chiave se necessario

”Installazione Pod fallita”

Sintomi:

• I problemi di costruzione si verificano durante l'installazione di CocoaPods
• Errori in Podfile

Soluzioni:

1. Verifica che Podfile.lock sia stato commesso

   git status ios/App/Podfile.lock

2. Testa l'installazione di pod localmente

   cd ios/App
   pod install

3. Controlla per pods incompatibili

   • Verifica Podfile per conflitti di versione
   • Assicurati che tutti i pods supportino il tuo target di distribuzione iOS

4. Cancella cache del pod

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

Problemi di costruzione per Android

”Keystore password incorrect”

Sintomi:

• La costruzione fallisce durante la firma
• Errori di Gradle sul keystore

Soluzioni:

1. Verifica la password del keystore

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

2. Verifica le variabili di ambiente

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

3. Verifica l'encoding base64

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

Chiave alias non trovata

Sintomi:

• La firma fallisce con errore di alias

Soluzioni:

1. Elenco degli alias del keystore

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

2. Verifica che l'alias corrisponda esattamente

   • L'alias è case-sensitive
   • Controlla per errori di ortografia in KEYSTORE_KEY_ALIAS

3. Utilizza l'alias corretto dal keystore

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

”Esecuzione del build di Gradle fallita”

Sintomi:

• Error di Gradle generici
• Issue di compilazione o dipendenza

Soluzioni:

1. Testa la costruzione locale prima

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Controlla le dipendenze mancanti

   • Recensisci i file build.gradle
   • Assicurati che tutti i plugin siano elencati nelle dipendenze

3. Verifica la compatibilità della versione di Gradle

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

4. Pulisci cache Gradle

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

”Errore di caricamento su Play Store”

Sintomi:

• La compilazione ha successo ma il caricamento fallisce
• Errori di account di servizio

Soluzioni:

1. Verifica il file JSON dell'account di servizio

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

2. Verifica i permessi dell'account di servizio

   • Vai a Console di Gioco → Configurazione → API Accesso
   • Assicurati che l'account di servizio abbia accesso alla tua app
   • Concedi la

3. Rilascio ai percorsi di testing

   • permessi
   • Verifica che l'app sia configurata nella Console di Gioco

4. Check API is enabled

   • Google Play Developer API must be enabled
   • Verifica che __CAPGO_KEEP_0__ sia abilitato

Il Google Play Developer __CAPGO_KEEP_0__ deve essere abilitato prima di tutto, in Google Cloud Console, verifica che sia abilitato, Problemi generali

”Il lavoro non è stato trovato” o “Lo stato di costruzione non è disponibile”

Simptomi:

• Non è possibile verificare lo stato di costruzione
• Errori di ID del lavoro

Soluzioni:

1. Attendere un momento e riprovare

   • Il lavoro di costruzione potrebbe richiedere alcuni secondi per inizializzare

2. Verificare che l'ID del lavoro sia corretto

   • Verificare l'ID del lavoro dalla risposta di costruzione iniziale

3. Verificare che la costruzione non sia scaduta

   • I dati di costruzione sono disponibili per 24 ore

”Project sync failed”

Sintomi:

• Il build fallisce prima che inizi la compilazione
• Errori di file mancanti

Soluzioni:

1. Esegui Capacitor sincronizzazione localmente

   bunx cap sync

2. Assicurati di aver commesso tutti i file nativi

   git status ios/ android/

3. Verifica file nativi ignorati da Git

   • Rivista .gitignore
   • Assicurati che i file di configurazione importanti non siano ignorati

”Il build è riuscito ma non vedo l’output”

Sintomi:

• Il build mostra successo ma non c’è il link di download

Soluzioni:

1. Verifica la configurazione del build

   • La memorizzazione degli artefatti potrebbe non essere configurata
   • Contatta il supporto se l'accesso agli artefatti non è disponibile per il tuo build

2. For l'invio di TestFlight su iOS

   • Controlla App Store Connect
   • Il processo potrebbe richiedere 5-30 minuti dopo l'upload

3. Per Android Play Store

   • Controlla Play Console → Testing → Internal testing
   • Il processo potrebbe richiedere alcuni minuti

Issue specifici del CI/CD

GitHub Azioni: “Comando non trovato”

Sintomi:

• bunx @capgo/cli@latest … fallisce in CI con “comando non trovato”

Soluzioni:

1. Configura Bun prima di tutto così bunx è disponibile:

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

2. Poi esegui il comando CLI — bunx lo carica a richiesta, non è necessaria l'installazione globale:

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

GitHub Azioni: “Segreti non trovati”

Sintomi:

• Variabili di ambiente vuote nella build

Soluzioni:

1. Verifica che i segreti siano impostati

   • Vai alle impostazioni del repository → Segreti e variabili → Azioni
   • Aggiungi tutti i segreti richiesti

2. Utilizza la sintassi corretta

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

3. Controlla che i nomi dei segreti corrispondano

   • I nomi sono case-sensitive
   • Nessun errore di ortografia nelle referenze ai segreti

Ottenere Maggiore Aiuto

Abilita la registrazione dettagliata

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

Raccogli informazioni di costruzione

Quando contatti il supporto, includi:

1. Comando di costruzione utilizzato

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

2. Messaggio di errore (output completo)

3. ID del lavoro (dalla output di costruzione)

4. Log dei build (copia l'output completo del terminale)

5. Informazioni sull'ambiente

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

Contattare il Supporto

• Unisciti alla nostra community: Email
• supporto@__CAPGO_KEEP_0__.app: support@capgo.app
• Documentazione: Capgo Docs

Limitazioni note

Limitazioni correnti:

• Tempo massimo di costruzione: 10 minuti
• Dimensione massima di caricamento: ~500MB
• Il caricamento dei build iOS richiede 24 ore di leasing Mac, il caricamento sul Mac verrà messo in coda per garantire l'uso ottimale
• L'accessibilità del download degli artefatti di costruzione dipende dalla destinazione di costruzione e dalla configurazione di archiviazione degli artefatti

Queste limitazioni possono essere adattate in base alle risposte dei clienti.

Prescan ha bloccato il mio build

Capgo esegue un prescan locale prescan prima dell'upload. Correggi il ritrovamento segnalato, o ignora solo quel controllo id:

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

Vedi il catalogo completo: I controlli del prescan.

Risorse aggiuntive

• Avvio rapido - Guida di avvio iniziale
• Costruzioni iOS - Configurazione specifica per iOS
• Costruzioni Android - Configurazione specifica per Android
• Verifiche di prescan - Elenco completo delle verifiche di costruzione e delle bandiere di ignorazione
• CLI Riferimento - Documentazione completa del comando