Aller au contenu principal

Capacitor Développer avec WSL2 sous Windows

Exécutez votre toolchain web Capacitor dans WSL2 tandis que l'émulateur Android et les appareils restent sur Windows : pont adb, réseau en miroir, performances du système de fichiers, live reload et builds iOS avec Capgo Build.

Capacitor développement avec WSL2 sur Windows Capgo illustration du blog

WSL2 offre aux développeurs Windows un vrai shell Linux, ce qui compte quand les scripts, Dockerfiles et la CI de votre équipe supposent tous bash. Avec Capacitor, ça fonctionne bien, à une règle près : gardez la toolchain web dans WSL2 et l'émulateur Android, les appareils USB et Android Studio sur Windows. Reliez ensuite les deux avec adb.

Ce guide présente cette configuration, les détails réseau qui piègent souvent, et comment iOS s'intègre via Build Capgo.

Quand WSL2 vaut le coup

Utilisez WSL2 si :

  • 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 la structure Linux node_modules 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, 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 dossier home Linux, pas 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écider où se trouve le SDK Android

Deux configurations fonctionnelles :

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 publiées sur les stores, Live Updates Capgo envoyer les changements web depuis WSL2 sans toucher à Gradle ni au Capgo Build :

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

Problèmes courants avec WSL2

  • adb: device offline ou liste vide dans WSL2: le serveur adb Windows n’est pas lancé 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 un redémarrage: attendu sans réseau en mode miroir. Placez le WSL_HOST export dans ~/.bashrc pour qu’il soit recalculé, ou passez en mode miroir.
  • Vite ne détecte pas les changements de fichiers: le projet se trouve 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: WSL2 clocks drift after sleep. Run 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.

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.