Build di release Android senza Android Studio su Linux, Windows e CI

Android Studio è un ottimo IDE, ma non è necessario per produrre un build Android pronto per lo store. La android/ cartella in un progetto Capacitor contiene un Gradle wrapper che builda e firma da qualsiasi terminale. Questo è fondamentale per i server Linux senza display, per le macchine Windows dove Studio è lento e per la CI.

Questa guida spiega come generare un AAB firmato solo via CLI, mostrando poi la variante cloud con Build Capgo per i team che non vogliono tenere i keystore sui laptop.

Prerequisiti

• JDK 21 (java -version stampa 21).
• Riga di comando Android SDK con platform-tools, build-tools e la piattaforma corrispondente alla tua versione Capacitor (API 36 per Capacitor 8, API 35 per Capacitor 7). La Guida Linux e Guida Windows coprono l'installazione.
• ANDROID_HOME esportato, o android/local.properties con sdk.dir=....
• Un'app Capacitor con android/ generato da bunx cap add android.

1) Crea il keystore di firma

keytool fa parte del JDK su ogni piattaforma:

keytool -genkeypair -v \
  -keystore release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias release

Rispondi ai prompt e scegli una password per lo store e una per la chiave. Salva il file e entrambe le password nel tuo password manager o in un vault subito. Non fare mai commit release.jks.

Abilita Play App Signing quando crei l'app in Play Console. Google gestirà la chiave di firma finale e il tuo keystore diventerà una chiave di upload, resettabile in caso di smarrimento.

2) Configura la firma in Gradle

Tieni i segreti fuori da build.gradle. Crea android/keystore.properties (gitignored):

storeFile=/absolute/path/to/release.jks
storePassword=your-store-password
keyAlias=release
keyPassword=your-key-password

Poi fai riferimento a android/app/build.gradle:

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file("keystore.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            if (keystorePropertiesFile.exists()) {
                storeFile file(keystoreProperties['storeFile'])
                storePassword keystoreProperties['storePassword']
                keyAlias keystoreProperties['keyAlias']
                keyPassword keystoreProperties['keyPassword']
            }
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
        }
    }
}

Aggiungi android/keystore.properties e *.jks a .gitignore.

3) Incrementa la versione

Google Play rifiuta gli upload con una versionCode ha già visto in precedenza. Modifica android/app/build.gradle:

defaultConfig {
    versionCode 12
    versionName "1.4.0"
}

I team solitamente derivano versionCode dai numeri di esecuzione CI o dal numero di commit git per evitare modifiche manuali.

4) Build dell'AAB dal terminale

bun run build
bunx cap sync android
cd android
./gradlew bundleRelease

Su Windows usa .\gradlew.bat bundleRelease. Il bundle firmato viene salvato in android/app/build/outputs/bundle/release/app-release.aab.

Ti serve un APK per installazioni dirette con adb? ./gradlew assembleRelease genera app-release.apk sotto outputs/apk/release/. Installalo con adb install; la guida all'installazione adb copre i casi limite.

5) Verifica la firma

$ANDROID_HOME/build-tools/36.0.0/apksigner verify --print-certs app/build/outputs/apk/release/app-release.apk

Per un AAB, jarsigner -verify -verbose app-release.aab conferma la firma e il fingerprint del certificato. Confronta lo SHA-256 con quello mostrato in Play Console sotto Integrità dell'app.

6) Upload su Google Play da riga di comando

L'upload manuale tramite Play Console funziona. Per l'automazione, crea un service account in Google Cloud, concedigli l'accesso in Play Console sotto Utenti e autorizzazioni, e scarica la sua chiave JSON. Poi esegui l'upload con il Google Play Developer API o uno strumento come fastlane supply:

bundle exec fastlane supply --aab android/app/build/outputs/bundle/release/app-release.aab \
  --track internal --json_key play-service-account.json --package_name com.example.app

Il primo upload di una nuova app deve essere fatto manualmente in Play Console; API accetta solo build per app già esistenti.

7) L'alternativa cloud: Capgo Build per Android

Tutto quanto sopra funziona, ma lascia un keystore su ogni macchina che effettua la build. Capgo Build conserva il keystore in un vault cifrato, esegue la build dal android/ progetto che carichi, e può inviare l'AAB a un track di Play.

Salva le credenziali una volta sola:

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./release.jks \
  --keystore-alias "release" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

Oppure lascia bunx @capgo/cli@latest build init --platform android ti guidi. Poi ogni release è:

bun run build
bunx cap sync android
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release

I log scorrono nel terminale. Aggiungi --output-upload per ottenere un link di download per l'AAB o l'APK, e --ai-analytics per ricevere una spiegazione automatica di un build fallito. Lo stesso comando funziona su Windows, Linux, macOS e CI. Un esempio di GitHub Actions è disponibile nel guida alla build Android.

Poiché Capgo riceve solo il progetto nativo preparato, i registry privati npm e i segreti della build web restano nel tuo ambiente.

8) Smetti di ricostruire tutto per le modifiche web

Serve un Native Build firmato per aggiornamenti di plugin, permessi, icone e Capacitor. Per tutto il resto, dist/, Live Updates di Capgo puoi pushare il nuovo web bundle direttamente alle app installate:

bunx @capgo/cli@latest bundle upload --channel production

That removes most Gradle runs from your week.

Risoluzione problemi

• SDK location not found: imposta ANDROID_HOME o crea android/local.properties.
• Keystore was tampered with, or password was incorrect: password dello store errata, o il file è stato corrotto da una conversione CRLF in Git. Segna *.jks come binario in .gitattributes se deve essere versionato, cosa che non dovrebbe accadere.
• Unsupported class file major version: la versione del JDK è diversa dalla 21.
• Play rifiuta l'AAB: “firmato con una chiave diversa”: Play App Signing richiede la tua upload key. Usa il keystore registrato su Play Console o richiedi il reset della upload key.
• La build è lenta su Windows: escludi ~/.gradle e la SDK da Defender, e tieni il progetto in un percorso locale breve.
• Errore di memoria in Gradle: aggiungi org.gradle.jvmargs=-Xmx4g a android/gradle.properties.

Riassunto

Una Capacitor Android release richiede un JDK, la SDK e il Gradle wrapper, non Android Studio. Crea il keystore con keytool, firma tramite keystore.properties, build con bundleRelease, e carica con il Play API. Se vuoi togliere il keystore dai laptop e usare lo stesso comando su ogni OS, Capgo Build gestisce la firma e l'upload dal progetto preparato.