WSL2 bietet Windows-Entwicklern eine echte Linux-Shell, was wichtig ist, wenn die Skripte, Dockerfiles und CI-Pipelines deines Teams bash voraussetzen. Für Capacitor funktioniert das gut, mit einer Regel: Halte die Web-Toolchain in WSL2 und den Android-Emulator, USB-Geräte und Android Studio auf Windows. Verbinde die beiden dann über adb.
Dieser Guide zeigt das Setup, die Netzwerk-Details, die oft zu Problemen führen, und wie iOS Capgo Build.
Wann sich WSL2 lohnt
Nutze WSL2, wenn:
- Dein Repo bash-Skripte, Makefiles oder Husky-Hooks enthält, die in PowerShell fehlschlagen.
- Du dieselben Docker-Images lokal und in der CI ausführst.
- Du das Linux-
node_moduleslayout so lockfiles match your Linux CI.
WSL2 überspringen, wenn du nur Android Studio und ein Terminal brauchst. Die native Windows-Anleitung ist in dem Fall einfacher.
1) WSL2 und eine Distribution installieren
In einer erhöhten PowerShell:
wsl --install -d Ubuntu
Neustart, Ubuntu öffnen, deinen Linux-User erstellen. Update und Basics installieren:
sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash
2) Projekt im Linux-Dateisystem halten
Erstelle deine Projekte unter deinem Linux-Home, nicht unter /mnt/c:
mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install
Zugriff auf die Dateien aus Windows-Tools über \\wsl$\Ubuntu\home\you\dev\my-app. VS Code mit der WSL-Erweiterung öffnet es direkt mit code ..
Warum das wichtig ist: Cross-File-System-Zugriff über /mnt/c ist langsam bei den Tausenden kleinen Dateien in node_modules, und die inotify-Watcher, die Vite verwendet, feuern für Dateien auf dem Windows-Laufwerk nicht zuverlässig.
3) Entscheide, wo das Android SDK liegt
Zwei praktikable Layouts:
Layout A (empfohlen): SDK auf Windows, Gradle in WSL2 zeigt auf eine Linux-SDK-Kopie. Installiere Android Studio auf Windows für den Emulator und GUI-Tools, und installiere ein separates Command Line SDK in WSL2 für 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
Ja, das dupliziert ein paar hundert Megabyte. Im Gegenzug läuft Gradle mit Linux-Geschwindigkeit und berührt nie /mnt/c.
Layout B: alles auf Windows, WSL2 nur für den Web-Build. Du führst bun run build in WSL2 aus und cap sync sowie gradlew aus PowerShell auf denselben Dateien über \\wsl$. Es funktioniert, ist aber langsamer und mischt zwei Shells. Wähle es nur, wenn du nichts in WSL2 installieren kannst.
Der Rest dieses Guides geht von Layout A aus.
4) adb zwischen WSL2 und Windows brücken
Der Emulator und USB-Handys sind an Windows angeschlossen. Der WSL2-Gradle-Build und cap run android müssen darauf zugreifen. Halte einen einzelnen adb-Server auf Windows und lass WSL2 als Client fungieren.
Starte auf Windows den adb-Server, der auf allen Schnittstellen lauscht. Verwende das adb aus dem Windows SDK:
adb kill-server
adb -a -P 5037 nodaemon server
Lass dieses Fenster offen. Erlaube Port 5037 durch die Windows-Firewall für den virtuellen WSL-Adapter, falls gefragt.
Weise in WSL2 den adb-Client auf den Windows-Host:
export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices
Der Emulator oder dein Smartphone wird nun in WSL2 angezeigt. Die beiden adb-Binaries müssen dieselbe Hauptversion haben, daher aktualisiere platform-tools auf beiden Seiten gleichzeitig.
Mirrored Networking vereinfacht dies
Aktiviere auf Windows 11 22H2 oder neuer Mirrored Networking, damit WSL2 den Windows-Netzwerkstack teilt. Erstelle oder bearbeite %USERPROFILE%\.wslconfig:
[wsl2]
networkingMode=mirrored
Ausführen wsl --shutdown, Ubuntu neu starten und dann ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. Die Host-IP ändert sich nicht mehr bei jedem Neustart, und Live Reload wird dadurch einfacher.
Alternative: USB-Gerät in WSL2 übergeben
Wenn du adb vollständig in WSL2 für ein physisches Telefon nutzen möchtest, verwende usbipd-win:
winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3
Füge dann die udev-Regel aus dem Linux-Anleitung in WSL2 hinzu. Das hilft nicht für den Emulator, der weiterhin eine Netzwerkverbindung ist.
5) App ausführen
Mit gebrücktem adb funktioniert Capacitor wie unter 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 erfordert Android Studio auf demselben Rechner. Öffne stattdessen das android/ Ordner in Windows Android Studio über \\wsl$\Ubuntu\home\you\dev\my-app\android. Das mitgelieferte Gradle von Studio baut dann auf Windows, während dein Terminal in WSL2 baut; beide teilen sich dieselben Quelldateien.
6) Live Reload über die Grenze hinweg
Vite läuft in WSL2, die App auf einem Windows-Emulator oder einem Smartphone. Der Emulator muss den Dev-Server erreichen.
Vite an alle Interfaces binden:
bun run dev -- --host 0.0.0.0
Capacitor darauf 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 ist der Alias des Emulators für den Host. Bei gespiegeltem Networking ist der WSL2-Port auf dem Windows-Host sichtbar, sodass diese Adresse Vite erreicht. Ohne gespiegeltes Networking den Port zuerst auf Windows weiterleiten:
netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)
Bei einem Smartphone per USB ersetze die URL durch deine Windows-LAN-IP und gib Port 5173 in der Windows-Firewall frei. Führe bunx cap sync android nach der Konfigurationsänderung aus und entferne den server -Block vor dem Release-Build.
7) iOS aus WSL2 mit Capgo Build
Xcode braucht macOS, deshalb übernimmt WSL2 alles bis zum nativen Kompilieren und Capgo erledigt den Rest:
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
CLI lädt das vorbereitete ios/ Projekt hoch und streamt die Logs zurück in dein WSL2-Terminal. Signing-Material wird ohne Mac erstellt, mit OpenSSL oder iOS-Zertifikatsgenerator. Alle Details findest du in Eine iOS-App unter Linux bauen mit Capacitor und Capgo Build, was für WSL2 unverändert gilt.
8) Native Builds für tägliche Änderungen vermeiden
Sobald beide Apps in den Stores sind, Capgo Live Updates Web-Änderungen aus WSL2 pushen, ohne Gradle oder Capgo Build anzufassen:
bunx @capgo/cli@latest bundle upload --channel production
Häufige WSL2-Probleme
adb: device offlineoder leere Liste in WSL2: Der Windows-ADB-Server läuft nicht mit-a, oder die Versionen unterscheiden sich. Neustart und Vergleichadb versionauf beiden Seiten.- Host-IP nach Neustart geändert: ohne mirrored networking zu erwarten. Setze die
WSL_HOSTexport in~/.bashrcso sie neu berechnet wird, oder wechsle in den mirrored-Modus. - Vite erkennt Dateiänderungen nicht: Projekt liegt unter
/mnt/c. Verschiebe es ins Linux-Home. - Gradle extrem langsam: gleiche Ursache, oder der Gradle-Cache liegt auf
/mnt/c. Behalte ihn~/.gradlein WSL2. - Clock Drift bricht die Apple-API-Authentifizierung bei
build init: WSL2-Uhren gehen nach dem Standby falsch. Führesudo hwclock -sand retry. cap open androidschlägt fehl: Studio läuft auf Windows. Öffne den Ordner stattdessen aus Studio.
Zusammenfassung
WSL2 ist ein guter Ort für die Capacitor-Web-Toolchain, wenn dein Team in Bash arbeitet. Behalte Emulator und Geräte auf Windows, verbinde sie über einen einzigen adb-Server, halte Dateien im Linux-Dateisystem und lass Capgo Build die iOS-Kompilierung übernehmen. Das Ergebnis ist ein Linux-Workflow auf einem Windows-Laptop, der trotzdem in beide App-Stores liefert.