Salta al contenuto principale

Sviluppo con Capacitor su Linux: la guida completa al setup

Configura un workflow completo di Capacitor su Ubuntu, Fedora o Arch: Node o Bun, JDK, SDK Android, emulatore con KVM, dispositivi USB con regole udev e build iOS senza Mac usando Capgo Build.

Guida alla configurazione di Capacitor su Linux Capgo illustrazione del blog

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:

  1. Compila i tuoi asset web e sincronizzali in ios/.
  2. Salva le credenziali di firma iOS una sola volta.
  3. 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_HOME non è esportato nella shell che esegue Gradle. Aggiungilo al tuo profilo e apri un nuovo terminale, oppure crea android/local.properties con sdk.dir=/home/you/Android/Sdk.
  • Unsupported class file major version: JDK errato. Imposta JAVA_HOME su JDK 21.
  • Schermo nero o lentezza estrema dell'emulatore: KVM non attivo. Verifica ls -l /dev/kvm e l'appartenenza al gruppo.
  • adb devices mostra no permissions: regola udev mancante o non ricaricata. Scollega e ricollega dopo il reload.
  • Il daemon Gradle esaurisce la memoria: aggiungi org.gradle.jvmargs=-Xmx4g a android/gradle.properties.
  • Glitch con Wayland e Android Studio: avvia Studio con _JAVA_AWT_WM_NONREPARENTING=1 se 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.

Live updates per le app Capacitor

Quando un bug nel web-layer è live, rilascia la fix tramite Capgo invece di aspettare giorni l'approvazione degli store. Gli utenti ricevono l'update in background, mentre le modifiche native restano nel normale processo di review.

Ultimi articoli dal blog

Capgo ti offre gli insight migliori che ti servono per creare un'app mobile davvero professionale.