Sviluppo Capacitor con WSL2 su Windows

WSL2 offre agli sviluppatori Windows una vera shell Linux, fondamentale quando gli script, i Dockerfile e la CI del team assumono l'uso di bash. Per Capacitor funziona bene, con una regola: tieni la toolchain web in WSL2 e l'emulatore Android, i dispositivi USB e Android Studio su Windows. Poi connetti i due tramite adb.

Questa guida mostra come configurare il tutto, i dettagli di networking che spesso creano problemi e come si integra iOS tramite Build Capgo.

Quando conviene usare WSL2

Usa WSL2 se:

• Il tuo repo ha script bash, Makefile o hook Husky che non funzionano su PowerShell.
• Esegui le stesse immagini Docker in locale e nella CI.
• Vuoi un ambiente Linux node_modules così i lockfile corrispondono alla tua CI Linux.

Salta WSL2 se ti servono solo Android Studio e un terminale. In quel caso, la guida nativa per Windows è più semplice in questo caso.

1) Installa WSL2 e una distribuzione

Da una PowerShell con privilegi di amministratore:

wsl --install -d Ubuntu

Riavvia, apri Ubuntu e crea il tuo utente Linux. Aggiorna e installa i pacchetti base:

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

2) Mantieni il progetto nel file system Linux

Crea i tuoi progetti nella home di Linux, non sotto /mnt/c:

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

Accedi ai file dagli strumenti Windows tramite \\wsl$\Ubuntu\home\you\dev\my-app. VS Code con l'estensione WSL lo apre direttamente con code ..

Perché è importante: l'accesso cross-file-system tramite /mnt/c è lento con le migliaia di piccoli file in node_modules, e gli inotify watcher usati da Vite non funzionano in modo affidabile per i file sul drive Windows.

3) Decidi dove risiede l'SDK di Android

Due configurazioni possibili:

Layout A (consigliato): SDK su Windows, Gradle in WSL2 che punta a una copia SDK su Linux. Installa Android Studio su Windows per l'emulatore e gli strumenti GUI, e installa un SDK da riga di comando separato dentro WSL2 per 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

Sì, duplica qualche centinaio di megabyte. In cambio, Gradle gira alla velocità di Linux e non tocca mai /mnt/c.

Layout B: tutto su Windows, WSL2 solo per la build web. Esegui bun run build in WSL2 e cap sync più gradlew da PowerShell sugli stessi file tramite \\wsl$. Funziona, ma è più lento e mescola due shell diverse. Sceglilo solo se non puoi installare nulla in WSL2.

Il resto di questa guida presuppone il Layout A.

4) Bridge di adb tra WSL2 e Windows

L'emulatore e i telefoni USB sono collegati a Windows. La build Gradle in WSL2 e cap run android devono raggiungerli. Mantieni un singolo server adb su Windows e lascia che WSL2 agisca da client.

Su Windows, avvia il server adb in ascolto su tutte le interfacce. Usa l'adb dal SDK di Windows:

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

Lascia quella finestra aperta. Se richiesto, consenti il passaggio della porta 5037 nel firewall di Windows per l'adattatore virtuale WSL.

In WSL2, indirizza il client adb verso l'host Windows:

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

L'emulatore o il tuo telefono ora compare dentro WSL2. I due binari adb devono avere la stessa versione major, quindi aggiorna platform-tools su entrambi i lati contemporaneamente.

Il networking in modalità mirrored semplifica questo

Su Windows 11 22H2 o versioni successive, abilita il mirrored networking in modo che WSL2 condivida lo stack di rete di Windows. Crea o modifica %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Esegui wsl --shutdown, riapri Ubuntu, quindi usa ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. L'IP dell'host non cambia più a ogni riavvio, e anche il live reload diventa più semplice.

Alternativa: passa il dispositivo USB in WSL2

Se vuoi adb interamente dentro WSL2 per un telefono fisico, usa usbipd-win:

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

Poi aggiungi la regola udev dal Guida Linux dentro WSL2. Questo non aiuta per l'emulatore, che resta una connessione di rete.

5) Avvia l'app

Con adb in bridge, Capacitor funziona come su 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 richiede Android Studio sulla stessa macchina. Invece, apri la android/ cartella in Windows Android Studio tramite \\wsl$\Ubuntu\home\you\dev\my-app\androidIl Gradle incluso in Studio esegue il build su Windows, mentre il terminale lo esegue in WSL2; entrambi condividono gli stessi file sorgente.

6) Live reload tra i due ambienti

Vite gira in WSL2, l'app gira su un emulatore Windows o su un telefono. L'emulatore deve raggiungere il dev server.

Avvia Vite in ascolto su tutte le interfacce:

bun run dev -- --host 0.0.0.0

Punta Capacitor a quell'indirizzo in 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 è l'alias dell'emulatore per la macchina host. Con il mirrored networking la porta WSL2 è visibile sull'host Windows, quindi questo indirizzo raggiunge Vite. Senza mirrored networking, fai prima il port forwarding su Windows:

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

Per un telefono via USB, sostituisci l'URL con l'IP LAN di Windows e apri la porta 5173 nel firewall di Windows. Esegui bunx cap sync android dopo aver modificato la config, e rimuovi il server blocco prima di buildare una release.

7) iOS da WSL2 con Capgo Build

Xcode richiede macOS, quindi WSL2 gestisce tutto fino alla compilazione nativa e Capgo fa il resto:

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

Il CLI effettua l'upload del ios/ progetto preparato e trasmette i log nel terminale WSL2. I certificati di signing vengono creati senza un Mac, tramite OpenSSL o il generatore di certificati iOS. Trovi tutti i dettagli in Builda un'app iOS da Linux con Capacitor e Capgo Build, che per WSL2 rimane invariato.

8) Evita i native build per le modifiche quotidiane

Una volta che entrambe le app sono negli store, Live Updates di Capgo pusha le modifiche web da WSL2 senza toccare Gradle o Capgo Build:

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

Problemi comuni con WSL2

• adb: device offline o una lista vuota in WSL2: il server adb di Windows non è in esecuzione con -a, o le versioni differiscono. Riavialo e confronta adb version su entrambi i lati.
• L'IP dell'host è cambiato dopo il riavvio: previsto senza mirrored networking. Metti l' WSL_HOST esporta in ~/.bashrc per ricalcolarlo, o passa alla modalità mirrored.
• Vite non rileva le modifiche ai file: il progetto si trova in /mnt/c. Spostalo nella home di Linux.
• Gradle è estremamente lento: stessa causa, oppure la cache di Gradle è su /mnt/c. Mantieni ~/.gradle in WSL2.
• Il clock drift rompe l'autenticazione API di Apple durante build init: l'orario di WSL2 si sfascia dopo lo sleep. Esegui sudo hwclock -s e riprova.
• cap open android fallisce: Studio è su Windows. Apri la cartella direttamente da Studio.

Riassunto

WSL2 è un buon ambiente per la toolchain web di Capacitor quando il tuo team lavora in bash. Tieni emulatore e dispositivi su Windows, collegali con un unico server adb, lascia i file nel file system Linux e lascia che Capgo Build si occupi della compilazione iOS. Il risultato è un workflow Linux su un laptop Windows che pubblica comunque su entrambi gli app store.