Linux est une excellente plateforme pour le travail avec Capacitor. La couche web n'est que de l'outillage Node, l'outillage Android s'exécute nativement, et l'émulateur Linux avec KVM est souvent plus rapide que le même émulateur sur Windows. La seule lacune, c'est iOS : Xcode n'existe que sur macOS, il vous faut donc un service de build cloud pour cette partie.
Ce guide détaille une configuration Linux complète, testée sur Ubuntu 24.04, Fedora 42 et Arch. Il se termine par un build iOS depuis Linux en utilisant Build Capgo, vous pouvez donc déployer sur les deux stores sans posséder de Mac.
Ce qui fonctionne sur Linux et ce qui ne fonctionne pas
| Tâche | Linux |
|---|---|
| Développement web, Vite, outils du framework | Oui |
cap add android, cap sync, builds Gradle |
Oui |
| Émulateur Android | Oui, avec KVM |
| Appareil Android physique via USB | Oui, avec des règles udev |
| Débogage à distance Chrome DevTools | Oui |
cap add ios, cap sync ios (générer et copier) |
Oui, avec l'avertissement que CocoaPods est ignoré |
| Compiler, signer et archiver iOS | Non, nécessite macOS. Utilisez Capgo Build |
| Simulateur iOS | Non |
| Safari Web Inspector pour WebView iOS | Non |
Tout ce qui est marqué « Non » passe dans le cloud ou sur un vrai iPhone avec TestFlight. Nous y revenons à la fin.
1) Installer Node ou Bun
Le CLI de Capacitor nécessite Node 20 ou plus récent. Bun sert de runtime et de gestionnaire de paquets, et il est plus rapide à l'installation.
# 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
Vérifier les versions :
bun --version
node --version
2) Installer un JDK
Capacitor 7 et 8 nécessitent JDK 21. Les paquets de distribution font l'affaire.
# Ubuntu / Debian
sudo apt install -y openjdk-21-jdk
# Fedora
sudo dnf install -y java-21-openjdk-devel
# Arch
sudo pacman -S jdk21-openjdk
Définissez JAVA_HOME dans ~/.bashrc ou ~/.zshrc. Le chemin dépend de la distribution :
# 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
Si vous avez plusieurs JDK installés, Gradle choisit celui vers lequel JAVA_HOME pointe. Une version incorrecte apparaît comme Unsupported class file major version pendant cap run android.
3) Installer le SDK Android
Vous avez deux options. Android Studio vous offre les outils GUI. Les outils en ligne de commande seuls sont plus légers et suffisent pour le build.
Option A : Android Studio
Téléchargez l'archive tarball Linux sur le site d'Android Studio et extrayez-la :
sudo tar -xzf android-studio-*.tar.gz -C /opt
/opt/android-studio/bin/studio.sh
Lors du premier lancement, l'assistant de configuration installe le SDK dans ~/Android/Sdk.
Capacitor cap open android doit savoir où se trouve Studio :
export CAPACITOR_ANDROID_STUDIO_PATH=/opt/android-studio/bin/studio.sh
Option B : outils en ligne de commande uniquement
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
Ajoutez le SDK à votre profil de 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
Installez ce dont Capacitor a besoin et acceptez les licences :
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "emulator"
sdkmanager --licenses
Faites correspondre la version de la compileSdkVersion in your generated android/variables.gradle. Capacitor 8 utilise 36 ; Capacitor 7 utilise 35.
4) Activer KVM pour l'émulateur
Sans KVM, l'émulateur est inutilisable. Vérifiez que votre CPU expose la virtualisation :
egrep -c '(vmx|svm)' /proc/cpuinfo
Un résultat supérieur à 0 signifie qu'il est supporté. Installez KVM et donnez l'accès à votre utilisateur :
# 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
Déconnectez-vous puis reconnectez-vous. Créez et lancez un appareil :
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
Si l'émulateur se plaint de /dev/kvm permissions, votre changement de groupe n’a pas encore été appliqué. Redémarrez.
5) Accès USB pour les appareils physiques
Linux does not let regular users talk to USB devices by default. Add a udev rule:
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
Les vendor IDs ci-dessus couvrent Google, Samsung et OnePlus. Trouvez le vôtre avec lsusb si votre téléphone n'est pas listé. Activez le débogage USB sur le téléphone, branchez-le, acceptez le prompt d'empreinte, puis :
adb devices
6) Créer le projet 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 sur Linux affiche un avertissement indiquant que CocoaPods est indisponible. C'est normal. Le ios/ dossier est tout de même créé et c'est ce que Capgo Build compile ensuite.
Lancez sur l'émulateur ou l'appareil :
bunx cap run android
Débuguez la WebView dans Chrome sur chrome://inspect.
7) Les builds de release sur Linux
Les builds de release Android sont entièrement locaux. Générez un keystore avec le keytool:
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
Puis compilez :
cd android
./gradlew bundleRelease
L'AAB se trouve dans android/app/build/outputs/bundle/release/. Si vous préférez ne pas garder de clés de signature sur vos ordinateurs, Capgo Build pour Android stocke le keystore une seule fois et effectue le build dans le cloud à partir du même CLI que pour iOS.
8) iOS depuis Linux avec Capgo Build
C'est l'étape que Linux ne peut pas faire seul. Le workflow :
- Compilez vos assets web et synchronisez-les dans
ios/. - Save your iOS signing credentials once.
- Lancez un build cloud. Capgo compile, signe et peut effectuer l'upload vers 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 vous guide pour les identifiants. Sur Linux, vous créez manuellement la clé API App Store Connect dans le portail Apple ; le Guide de build iOS montre chaque étape. Pour le certificat de distribution, pas besoin de Keychain Access : générez le CSR et .p12 avec OpenSSL comme décrit dans les certificats iOS et les profils de provisionnement expliqués, ou utilisez le Générateur de certificats iOS.
Les logs s'affichent en direct dans votre terminal. Le flux complet de Linux vers TestFlight est détaillé dans Compilez une app iOS depuis Linux avec Capacitor et Capgo Build.
9) Éviter les rebuilds natifs avec Live Updates
Une fois les shells natifs publiés sur les stores, la plupart des modifications quotidiennes concernent le JavaScript, le HTML et le CSS. Vous pouvez les déployer depuis Linux en quelques secondes avec Live Updates Capgo:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
Réservez les builds natifs aux modifications de plugins, de permissions et aux mises à niveau Capacitor.
Problèmes courants sur Linux
SDK location not found:ANDROID_HOMEn’est pas exporté dans le shell qui exécute Gradle. Ajoutez-l’à votre profil et ouvrez un nouveau terminal, ou créezandroid/local.propertiesparsdk.dir=/home/you/Android/Sdk.Unsupported class file major version: JDK incorrect. PointezJAVA_HOMEvers JDK 21.- Écran noir ou émulateur très lent : KVM n’est pas actif. Vérifiez
ls -l /dev/kvmet l'appartenance à votre groupe. adb devicesafficheno permissions: règle udev manquante ou non rechargée. Débranchez puis rebranchez après le rechargement.- Le daemon Gradle manque de mémoire: ajouter
org.gradle.jvmargs=-Xmx4gversandroid/gradle.properties. - Glitchs avec Wayland et Android Studio: lancez Studio avec
_JAVA_AWT_WM_NONREPARENTING=1si les fenêtres restent blanches.
Résumé
Linux gère nativement toute la boucle Capacitor pour Android et la couche web, et souvent plus vite que d'autres OS de bureau. Pour iOS, générez le projet en local, synchronisez vos assets et laissez Capgo Build s'occuper de la partie macOS. Ajoutez les Live Updates et vous ne penserez à Xcode que le jour où Apple changera sa SDK minimale.