Aller au contenu principal

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

Mettez en place un workflow complet Capacitor sur Ubuntu, Fedora ou Arch : Node ou Bun, JDK, SDK Android, émulateur avec KVM, appareils USB avec règles udev, et builds iOS sans Mac grâce à Capgo Build.

Capacitor Guide de configuration pour le développement sur Linux Capgo illustration de blog

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 :

  1. Compilez vos assets web et synchronisez-les dans ios/.
  2. Save your iOS signing credentials once.
  3. 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_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 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 puis rebranchez après le rechargement.
  • Le daemon Gradle manque de mémoire: ajouter org.gradle.jvmargs=-Xmx4g vers android/gradle.properties.
  • Glitchs avec Wayland et Android Studio: lancez Studio avec _JAVA_AWT_WM_NONREPARENTING=1 si 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.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.