Linux è un'ottima piattaforma per il lavoro con Capacitor. Lo strato web è solo tooling Node, il tooling Android gira nativamente e l'emulatore Linux con KVM è spesso più veloce dello stesso emulatore su Windows. L'unica lacuna è iOS: Xcode esiste solo su macOS, quindi per quella parte serve un servizio di build cloud.
Questa guida illustra una configurazione completa su Linux, testata su Ubuntu 24.04, Fedora 42 e Arch. Si conclude con una build iOS da Linux utilizzando Build Capgo, così puoi pubblicare su entrambi gli store senza avere un Mac.
Cosa funziona su Linux e cosa no
| Attività | Linux |
|---|---|
| Sviluppo web, Vite, tooling per framework | Sì |
cap add android, cap sync, build Gradle |
Sì |
| Emulatore Android | Sì, con KVM |
| Dispositivo Android fisico via USB | Sì, con le regole udev |
| Remote debugging con Chrome DevTools | Sì |
cap add ios, cap sync ios (genera e copia) |
Sì, con l'avviso che CocoaPods viene saltato |
| Compila, firma e archivia iOS | No, serve macOS. Usa Capgo Build |
| Simulatore iOS | No |
| Safari Web Inspector per iOS WebView | No |
Tutto quello che c'è nelle righe “No” passa al cloud o su un iPhone reale con TestFlight. Ne parliamo alla fine.
1) Installa Node o Bun
Capacitor's CLI richiede Node 20 o superiore. Bun funziona come runtime e package manager ed è più veloce per le installazioni.
# Bun (recommended)
curl -fsSL https://bun.sh/install | bash
# Or Node via your package manager
# Ubuntu / Debian
sudo apt install -y nodejs npm
# Fedora
sudo dnf install -y nodejs
# Arch
sudo pacman -S nodejs npm
Verifica le versioni:
bun --version
node --version
2) Installa un JDK
Capacitor 7 e 8 richiedono JDK 21. I pacchetti di distribuzione vanno bene.
# Ubuntu / Debian
sudo apt install -y openjdk-21-jdk
# Fedora
sudo dnf install -y java-21-openjdk-devel
# Arch
sudo pacman -S jdk21-openjdk
Imposta JAVA_HOME nella ~/.bashrc oppure ~/.zshrc. Il percorso dipende dalla distribuzione:
# Ubuntu / Debian
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# Fedora
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
# Arch
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
Se hai più di un JDK installato, Gradle sceglie quello che JAVA_HOME indica. Una versione errata appare come Unsupported class file major version durante cap run android.
3) Installa l'Android SDK
Hai due opzioni. Android Studio offre gli strumenti GUI. I soli command line tools sono più leggeri e sufficienti per il build.
Opzione A: Android Studio
Scarica il tarball Linux dal sito di Android Studio ed estrailo:
sudo tar -xzf android-studio-*.tar.gz -C /opt
/opt/android-studio/bin/studio.sh
Al primo avvio, la procedura di configurazione installa SDK in ~/Android/Sdk.
di Capacitor cap open android deve sapere dove si trova Studio:
export CAPACITOR_ANDROID_STUDIO_PATH=/opt/android-studio/bin/studio.sh
Opzione B: Solo command line tools
mkdir -p ~/Android/Sdk/cmdline-tools
cd ~/Android/Sdk/cmdline-tools
# Download "Command line tools only" for Linux from the Android developer site, then:
unzip commandlinetools-linux-*.zip
mv cmdline-tools latest
Aggiungi SDK al tuo profilo shell:
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator
Installa le dipendenze di Capacitor e accetta le licenze:
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "emulator"
sdkmanager --licenses
Allinea la versione della piattaforma a quella compileSdkVersion nel tuo generato android/variables.gradlegenerato. Capacitor 8 usa 36; Capacitor 7 usa 35.
4) Abilita KVM per l'emulatore
Senza KVM l'emulatore è inutilizzabile. Verifica che la CPU esponga la virtualizzazione:
egrep -c '(vmx|svm)' /proc/cpuinfo
Un valore superiore a 0 indica che è supportato. Installa KVM e concedi l'accesso al tuo utente:
# Ubuntu / Debian
sudo apt install -y qemu-kvm
# Fedora
sudo dnf install -y qemu-kvm
# Arch
sudo pacman -S qemu-base
sudo usermod -aG kvm $USER
Esci e rientra. Crea e avvia un dispositivo:
sdkmanager "system-images;android-36;google_apis;x86_64"
avdmanager create avd -n pixel8 -k "system-images;android-36;google_apis;x86_64" -d pixel_8
emulator -avd pixel8
Se l'emulatore segnala un problema di /dev/kvm permessi, il cambio di gruppo non è ancora stato applicato. Riavvia.
5) Accesso USB per dispositivi fisici
Su Linux, gli utenti standard non possono comunicare con i dispositivi USB in modo predefinito. Aggiungi una regola udev:
sudo tee /etc/udev/rules.d/51-android.rules > /dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="2a70", MODE="0666", GROUP="plugdev"
EOF
sudo udevadm control --reload-rules
sudo usermod -aG plugdev $USER
Gli ID vendor sopra coprono Google, Samsung e OnePlus. Trova il tuo con lsusb se il tuo telefono non è elencato. Abilita il debug USB sul telefono, collegalo, accetta la richiesta di impronta digitale, quindi:
adb devices
6) Crea il progetto Capacitor
bun create vite@latest my-app
cd my-app
bun install
bun add @capacitor/core @capacitor/android @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add android
bunx cap add ios
cap add ios su Linux stampa un avviso che CocoaPods non è disponibile. È previsto. La ios/ cartella viene comunque creata ed è ciò che Capgo Build compila in seguito.
Esegui sull'emulatore o sul dispositivo:
bunx cap run android
Debugga la WebView in Chrome su chrome://inspect.
7) Build di rilascio su Linux
Le build di rilascio per Android sono completamente locali. Genera un keystore con il JDK keytool:
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
Poi compila:
cd android
./gradlew bundleRelease
L'AAB arriva in android/app/build/outputs/bundle/release/. Se preferisci non conservare le chiavi di firma sui laptop, Capgo Build per Android conserva il keystore una sola volta e compila nel cloud dallo stesso CLI che usi per iOS.
8) iOS da Linux con Capgo Build
Questo è il passaggio che Linux non può eseguire da solo. Il workflow:
- Compila i tuoi asset web e sincronizzali in
ios/. - Salva le credenziali di firma iOS una sola volta.
- Richiedi una build nel cloud. Capgo compila, firma e può caricare su TestFlight.
bun run build
bunx cap sync ios
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
build init ti guida attraverso le credenziali. Su Linux crei manualmente la chiave API di App Store Connect nel portale Apple; il Guida build iOS mostra ogni clic. Per il certificato di distribuzione non ti serve mai Keychain Access: genera il CSR e .p12 con OpenSSL come descritto in Certificati iOS e provisioning profile spiegati, oppure usa il Generatore di certificati iOS.
I log arrivano in tempo reale nel terminale. Il flusso completo da Linux a TestFlight è dettagliato in Crea un'app iOS da Linux con Capacitor e Capgo Build.
9) Evita i rebuild nativi con Live Updates
Una volta che le shell native sono negli store, la maggior parte delle modifiche quotidiane riguarda JavaScript, HTML e CSS. Queste possono essere pubblicate da Linux in pochi secondi con Live Updates di Capgo:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
Riserva i build nativi per modifiche ai plugin, alle autorizzazioni e agli upgrade di Capacitor.
Problemi comuni su Linux
SDK location not found:ANDROID_HOMEnon è esportato nella shell che esegue Gradle. Aggiungilo al tuo profilo e apri un nuovo terminale, oppure creaandroid/local.propertiesconsdk.dir=/home/you/Android/Sdk.Unsupported class file major version: JDK errato. ImpostaJAVA_HOMEsu JDK 21.- Schermo nero o lentezza estrema dell'emulatore: KVM non attivo. Verifica
ls -l /dev/kvme l'appartenenza al gruppo. adb devicesmostrano permissions: regola udev mancante o non ricaricata. Scollega e ricollega dopo il reload.- Il daemon Gradle esaurisce la memoria: aggiungi
org.gradle.jvmargs=-Xmx4gaandroid/gradle.properties. - Glitch con Wayland e Android Studio: avvia Studio con
_JAVA_AWT_WM_NONREPARENTING=1se le finestre restano vuote.
Riassunto
Linux gestisce l'intero ciclo Capacitor per Android e per il layer web in modo nativo, spesso più velocemente di altri desktop. Per iOS, genera il progetto localmente, sincronizza le tue risorse e lascia che Capgo Build si occupi della parte macOS. Abbina questo a Live Updates e l'unico momento in cui penserai a Xcode sarà quando Apple cambierà il suo SDK minimo.