Capacitor Développer avec WSL2 sous Windows

WSL2 offre aux développeurs Windows un véritable shell Linux, ce qui est crucial quand les scripts, Dockerfiles et CI de votre équipe reposent sur bash. Pour Capacitor, cela fonctionne parfaitement avec une règle : gardez la toolchain web dans WSL2 et l'émulateur Android, les appareils USB et Android Studio sur Windows. Utilisez ensuite adb pour créer un pont entre les deux.

Ce guide présente cette configuration, les détails réseau qui posent souvent problème, et comment intégrer iOS via Build Capgo.

Quand WSL2 en vaut la peine

Utilisez WSL2 quand :

• Votre repo contient des scripts bash, des Makefiles ou des hooks Husky qui plantent sous PowerShell.
• Vous utilisez les mêmes images Docker en local et en CI.
• Vous voulez l'environnement node_modules Linux pour que les lockfiles correspondent à votre CI Linux.

Oubliez WSL2 si vous n'avez besoin que d'Android Studio et d'un terminal. Le guide Windows natif est plus simple dans ce cas.

1) Installer WSL2 et une distribution

Depuis un PowerShell en mode administrateur :

wsl --install -d Ubuntu

Redémarrez, ouvrez Ubuntu et créez votre utilisateur Linux. Mettez à jour et installez les bases :

sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash

2) Gardez le projet dans le système de fichiers Linux

Créez vos projets dans votre home Linux, et non sous /mnt/c:

mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install

Accédez aux fichiers depuis les outils Windows via \\wsl$\Ubuntu\home\you\dev\my-app. VS Code avec l'extension WSL l'ouvre directement avec code ..

Pourquoi c'est important : l'accès entre systèmes de fichiers via /mnt/c est lent pour les milliers de petits fichiers dans node_modules, et les watchers inotify utilisés par Vite ne se déclenchent pas de manière fiable pour les fichiers sur le lecteur Windows.

3) Décidez où se trouve le SDK Android

Deux configurations possibles :

Configuration A (recommandée) : SDK sur Windows, Gradle dans WSL2 pointant vers une copie SDK Linux. Installez Android Studio sur Windows pour l'émulateur et les outils GUI, et installez un SDK en ligne de commande séparé dans WSL2 pour Gradle :

mkdir -p ~/Android/Sdk/cmdline-tools && cd ~/Android/Sdk/cmdline-tools
# download commandlinetools-linux-*.zip from the Android developer site
unzip commandlinetools-linux-*.zip && mv cmdline-tools latest
echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools' >> ~/.bashrc
source ~/.bashrc
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
sdkmanager --licenses

Oui, cela duplique quelques centaines de mégaoctets. En échange, Gradle tourne à la vitesse de Linux et ne touche jamais /mnt/c.

Configuration B : tout sur Windows, WSL2 uniquement pour le build web. Vous exécutez bun run build dans WSL2 et cap sync , ce qui gradlew depuis PowerShell sur les mêmes fichiers via \\wsl$Cela fonctionne, mais c'est plus lent et cela mélange deux shells. Ne choisissez cette option que si vous ne pouvez rien installer dans WSL2.

Le reste de ce guide suppose la Configuration A.

4) Créer un pont adb entre WSL2 et Windows

L'émulateur et les téléphones USB sont connectés à Windows. Le build Gradle de WSL2 et cap run android doivent pouvoir les atteindre. Gardez un seul serveur adb sur Windows et laissez WSL2 agir en tant que client.

Sur Windows, lancez le serveur adb en écoute sur toutes les interfaces. Utilisez l'adb du SDK Windows :

adb kill-server
adb -a -P 5037 nodaemon server

Laissez cette fenêtre ouverte. Si on vous le demande, autorisez le port 5037 dans le pare-feu Windows pour l’adaptateur virtuel WSL.

Dans WSL2, faites pointer le client adb vers l’hôte Windows :

export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices

L’émulateur ou votre téléphone apparaît désormais dans WSL2. Les deux binaires adb doivent avoir la même version majeure, alors mettez à jour platform-tools des deux côtés en même temps.

Le mode réseau mirrored simplifie cela

Sur Windows 11 22H2 ou version ultérieure, activez le mirroring réseau pour que WSL2 partage la pile réseau de Windows. Créez ou modifiez %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Exécutez wsl --shutdown, rouvrez Ubuntu, puis utilisez ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. L’IP de l’hôte ne change plus à chaque redémarrage, et le live reload devient aussi plus simple.

Alternative : faites passer le périphérique USB dans WSL2

Si vous voulez faire tourner adb entièrement dans WSL2 pour un téléphone physique, utilisez usbipd-win :

winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3

Ajoutez ensuite la règle udev depuis le Guide Linux dans WSL2. Cela ne règle pas le cas de l'émulateur, qui reste une connexion réseau.

5) Lancer l'app

Avec adb en mode bridge, Capacitor fonctionne comme sous Linux :

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
bunx cap run android

cap open android nécessite Android Studio sur la même machine. Ouvrez plutôt le android/ dossier dans Android Studio sous Windows via \\wsl$\Ubuntu\home\you\dev\my-app\androidLe Gradle inclus dans Android Studio effectue le build sur Windows tandis que votre terminal build dans WSL2 ; les deux partagent les mêmes fichiers sources.

6) Live reload entre les deux environnements

Vite tourne dans WSL2, l'app tourne sur un émulateur Windows ou un téléphone. L'émulateur doit pouvoir joindre le serveur de dev.

Lancez Vite en écoute sur toutes les interfaces :

bun run dev -- --host 0.0.0.0

Faites pointer Capacitor dessus dans capacitor.config.ts:

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  server: {
    url: 'http://10.0.2.2:5173',
    cleartext: true,
  },
};

10.0.2.2 est l'alias de la machine hôte vu depuis l'émulateur. Avec le mirrored networking, le port WSL2 est visible sur l'hôte Windows, donc cette adresse permet de joindre Vite. Sans mirrored networking, redirigez d'abord le port côté Windows :

netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)

Pour un téléphone connecté en USB, remplacez l'URL par votre IP LAN Windows et ouvrez le port 5173 dans le pare-feu Windows. Lancez bunx cap sync android après avoir modifié la config, et supprimez le server bloc avant de compiler une release.

7) iOS depuis WSL2 avec Capgo Build

Xcode nécessite macOS : WSL2 gère donc tout jusqu'à la compilation native et Capgo s'occupe du reste :

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

Le CLI effectue l'upload du ios/ projet préparé et renvoie les logs dans votre terminal WSL2. Les éléments de signature sont créés sans Mac, via OpenSSL ou le Générateur de certificats iOS. Tous les détails se trouvent dans Compilez une app iOS depuis Linux avec Capacitor et Capgo Build, qui s'applique à WSL2 sans modification.

8) Évitez les builds natifs pour les changements quotidiens

Une fois les deux apps sur les stores, Capgo Live Updates poussez vos changements web depuis WSL2 sans toucher à Gradle ou au build Capgo :

bunx @capgo/cli@latest bundle upload --channel production

Problèmes WSL2 courants

• adb: device offline ou liste vide dans WSL2: le serveur adb Windows ne tourne pas avec -a, ou les versions diffèrent. Redémarrez-l’et comparez adb version des deux côtés.
• L'IP de l'hôte a changé après le reboot: normal sans le mirroring réseau. Mettez l' WSL_HOST export dans ~/.bashrc pour qu'il soit recalculé, ou passez en mode mirrored.
• Vite ne détecte pas les changements de fichiers: le projet est situé sous /mnt/c. Déplacez-le dans le home Linux.
• Gradle est extrêmement lent: même cause, ou le cache Gradle est sur /mnt/c. Gardez-le ~/.gradle dans WSL2.
• Le décalage d'horloge casse l'authentification Apple API lors de build init: l'horloge WSL2 se décale après la veille. Lancez sudo hwclock -s et réessayez.
• cap open android échoue: Studio est sur Windows. Ouvrez plutôt le dossier depuis Studio.

Résumé

WSL2 est un bon environnement pour la toolchain web Capacitor quand votre équipe travaille sous bash. Gardez l'émulateur et les appareils sur Windows, reliez-les via un seul serveur adb, conservez vos fichiers dans le système de fichiers Linux, et laissez le build Capgo gérer la compilation iOS. Le résultat : un workflow Linux sur un PC portable Windows qui publie toujours sur les deux stores.