Capacitor Développer sur Linux : le guide complet de configuration

Linux est une excellente plateforme pour le travail Capacitor. La couche web n'est que du tooling Node, les outils Android s'exécutent nativement, et l'émulateur Linux avec KVM est souvent plus rapide que le même émulateur sur Windows. Le seul manque est iOS : Xcode n'existe que sur macOS, vous avez donc besoin d'un service de cloud build 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, pour pouvoir déployer sur les deux stores sans posséder de Mac.

Ce qui fonctionne sur Linux et ce qui ne fonctionne pas

Tout ce qui est dans les lignes « Non » est transféré vers le cloud ou sur un iPhone réel via TestFlight. Nous détaillons cela à la fin.

1) Installez Node ou Bun

Le CLI de Capacitor nécessite Node 20 ou une version supérieure. Bun sert de runtime et de gestionnaire de paquets, et il est plus rapide pour les installs.

# 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érifiez les versions :

bun --version
node --version

2) Installez un JDK

Capacitor 7 et 8 nécessitent le JDK 21. Les paquets de distribution conviennent parfaitement.

# 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 plus d'un JDK installé, Gradle choisira celui vers lequel JAVA_HOME pointe le chemin. Une mauvaise version apparaîtra 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

Associez la version de la plateforme au 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'elle est supportée. 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 de l'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 plus tard.

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 JDK keytool:

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

Then build:

cd android
./gradlew bundleRelease

L'AAB se trouve dans android/app/build/outputs/bundle/release/. Si vous préférez ne pas conserver 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 celui utilisé pour iOS.

8) iOS depuis Linux avec Capgo Build

C'est l'étape que Linux ne peut pas réaliser seul. Le workflow :

1. Compilez vos assets web et synchronisez-les vers ios/.
2. Save your iOS signing credentials once.
3. Lancez un cloud build. 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 la clé API App Store Connect manuellement sur le portail Apple ; le Guide de build iOS montre chaque clic. Pour le certificat de distribution, l'accès au Trousseau n'est jamais nécessaire : 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) Évitez les rebuilds natifs avec les Live Updates

Une fois les shells natifs sur les stores, la plupart des changements quotidiens concernent le JavaScript, le HTML et le CSS. Vous pouvez les déployer depuis Linux en quelques secondes avec Capgo Live Updates:

bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production

Réservez les Native Build pour les changements de plugins, de permissions et les mises à jour Capacitor.

Problèmes courants sur Linux

• SDK location not found: ANDROID_HOME n'est pas exporté dans le shell qui exécute Gradle. Ajoutez-l’à votre profil et ouvrez un nouveau terminal, ou créez android/local.properties par sdk.dir=/home/you/Android/Sdk.
• Unsupported class file major version: JDK incorrect. Pointez JAVA_HOME vers le JDK 21.
• Écran noir ou émulateur très lent: KVM n'est pas actif. Vérifiez ls -l /dev/kvm et l'appartenance à votre groupe.
• adb devices affiche no permissions: règle udev manquante ou non rechargée. Débranchez et rebranchez après le rechargement.
• Le daemon Gradle manque de mémoire: ajouter org.gradle.jvmargs=-Xmx4g vers android/gradle.properties.
• Bugs Wayland et Android Studio: lancez Studio avec _JAVA_AWT_WM_NONREPARENTING=1 si Windows reste vide.

Résumé

Linux gère nativement l'intégralité de la boucle Capacitor pour Android et la couche web, et souvent plus rapidement que d'autres desktops. Pour iOS, générez le projet localement, synchronisez vos assets, et laissez Capgo Native Build s'occuper de la partie macOS. Couplez cela avec les Live Updates et la seule fois où vous penserez à Xcode sera quand Apple changera sa SDK minimale.