Android Studio è un ottimo IDE, ma non è necessario per produrre una build Android pronta per lo store. La android/ cartella generata 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 genera un AAB firmato solo da riga di comando, poi mostra la variante cloud con Build Capgo per i team che preferiscono non tenere i keystore sui laptop.
Prerequisiti
- JDK 21 (
java -versionstampa 21). - Android SDK da riga di comando con
platform-tools,build-toolse la piattaforma corrispondente alla tua versione Capacitor (API 36 per Capacitor 8, API 35 per Capacitor 7). La Guida Linux e Guida per Windows coprono l'installazione. ANDROID_HOMEesportata, oppureandroid/local.propertiesconsdk.dir=....- Un'app Capacitor con
android/generata dabunx 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 subito il file e entrambe le password nel tuo password manager o nel vault dei segreti. Non committare mai release.jks.
Abilita Play App Signing quando crei l'app in Play Console. Google poi conserva la chiave di firma finale e il tuo keystore diventa una chiave di upload, che può essere resettata se la perdi.
2) Configura la firma in Gradle
Tieni i segreti fuori da build.gradle. Crea android/keystore.properties (ignorato da Git):
storeFile=/absolute/path/to/release.jks
storePassword=your-store-password
keyAlias=release
keyPassword=your-key-password
Poi referenzialo in 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 un versionCode che ha già visto. Modifica android/app/build.gradle:
defaultConfig {
versionCode 12
versionName "1.4.0"
}
I team di solito derivano versionCode dai numeri delle esecuzioni CI o dal conteggio dei commit git per evitare modifiche manuali.
4) Genera l'AAB dal terminale
bun run build
bunx cap sync android
cd android
./gradlew bundleRelease
Su Windows usa .\gradlew.bat bundleRelease. Il bundle firmato viene scritto 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 ad adb install 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 indicato in Play Console sotto Integrità app.
6) Upload su Google Play dalla riga di comando
L'upload manuale tramite Play Console funziona. Per automatizzare, 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 Google Play Developer API o con 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: impostaANDROID_HOMEo creaandroid/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*.jkscome binario in.gitattributesse deve essere versionato, cosa che non dovrebbe accadere.Unsupported class file major version: the JDK is newer or older than 21.- Play rifiuta l'AAB: “firmato con una chiave diversa”Play App Signing si aspetta la tua upload key. Usa il keystore registrato in Play Console o richiedi un reset della upload key.
- La build è lenta su Windows: escludi
~/.gradlee il SDK da Defender, e mantieni il progetto su un percorso locale breve. - Out of memory in Gradle: aggiungi
org.gradle.jvmargs=-Xmx4gaandroid/gradle.properties.
Riassunto
Una release Android di Capacitor richiede un JDK, il SDK e il wrapper Gradle, non Android Studio. Crea il keystore con keytool, firma tramite keystore.properties, compila con bundleRelease, e fai l'upload con il Play API. Se vuoi tenere il keystore fuori dai laptop e usare lo stesso comando su ogni OS, Capgo Build gestisce firma e upload dal progetto preparato.