Capacitor-Entwicklung unter Windows: Der komplette Setup-Guide

Die meisten Capacitor Dokumentationen setzen einen Mac voraus. Bei der Entwicklung unter Windows funktionieren der Web-Layer und Android identisch, abgesehen von Windows-spezifischen Stolperfallen bei PowerShell, Pfadlängen und dem Emulator. iOS lässt sich unter Windows nicht kompilieren – die Lösung ist ein Cloud macOS Build.

Dieser Guide bietet das komplette Windows 11 Setup: vom leeren Rechner bis zum Android-Build auf dem Gerät und dem iOS-Build in TestFlight durch Capgo Build.

Was unter Windows funktioniert und was nicht

1) Node oder Bun installieren

Nutzt winget In PowerShell:

winget install OpenJS.NodeJS.LTS
# Or Bun
winget install Oven-sh.Bun

Öffne ein neues Terminal und bestätige:

node --version
bun --version

PowerShell-Execution-Policy korrigieren

bunx cap, npx cap und die meisten CLI-Shims sind .ps1 Skripte. Ein frisches Windows blockiert sie mit running scripts is disabled on this system. Erlaube lokale Skripte einmalig:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2) JDK 21 installieren

Capacitor 7 und 8 benötigen JDK 21. Android Studio bringt sein eigenes JBR mit, aber ein System-JDK vermeidet Überraschungen, wenn du Gradle im Terminal ausführst.

winget install Microsoft.OpenJDK.21

Setzen Sie JAVA_HOME für deinen User. In PowerShell:

[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot", "User")

Passe den Ordner an die installierte Version an. Starte das Terminal danach neu.

3) Android Studio und das SDK installieren

winget install Google.AndroidStudio

Starte Android Studio und lass den Setup-Assistenten das SDK installieren, C:\Users\<you>\AppData\Local\Android\Sdk. Setze dann die Umgebungsvariablen, nach denen Gradle und Capacitor suchen:

$sdk = "$env:LOCALAPPDATA\Android\Sdk"
[Environment]::SetEnvironmentVariable("ANDROID_HOME", $sdk, "User")
$path = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$path;$sdk\platform-tools;$sdk\emulator", "User")

Öffne den SDK Manager in Android Studio und installiere die Plattform passend zu deiner Capacitor-Version: API 36 für Capacitor 8, API 35 für Capacitor 7.

4) Emulator beschleunigen

Der Emulator braucht Hardware-Virtualisierung. Unter Windows 11 nutzt der Emulator die Windows Hypervisor Platform. Aktiviere sie:

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform

Starte neu. Wenn der Device Manager von Android Studio weiterhin vor fehlender Beschleunigung warnt, prüfe, ob die Virtualisierung im BIOS oder UEFI aktiviert ist und ob Core Isolation (Speicherintegrität) sie bei älteren CPUs blockiert.

Erstelle ein Gerät im Device Manager oder über das Terminal:

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

5) USB-Debugging unter Windows

Aktiviere die Entwickleroptionen und USB-Debugging auf dem Smartphone. Die meisten Handys brauchen keinen Treiber mehr, aber wenn adb devices leer bleibt, installiere den USB-Treiber von Google über den SDK Manager (SDK Tools-Tab) oder den Herstellertreiber für Samsung-Geräte.

adb devices

Bestätige beim ersten Mal die Fingerabdruck-Abfrage auf dem Smartphone.

6) Windows-spezifische Projekt-Fixes

Drei Einstellungen sparen Stunden unter Windows:

Lange Pfade. Gradle und node_modules können das 260-Zeichen-Limit überschreiten. Aktiviere lange Pfade einmalig:

git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Der zweite Befehl benötigt Administratorrechte in PowerShell.

Defender-Ausschlüsse. Echtzeit-Scans von node_modules, der Gradle-Cache und der Android SDK verlangsamen Builds spürbar. Schließe diese Ordner in der Windows-Sicherheit oder via PowerShell aus:

Add-MpPreference -ExclusionPath "$env:USERPROFILE\.gradle"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Android\Sdk"
Add-MpPreference -ExclusionPath "C:\dev"

Speichere deine Projekte in einem kurzen Pfad wie C:\dev\my-app, nicht unter OneDrive-synchronisierten Dokumenten.

Zeilenendungen. Gradles gradlew Shell-Skripte müssen LF-Endungen behalten, sonst bricht die Linux-CI ab. Füge ein .gitattributes:

*.sh text eol=lf
gradlew text eol=lf

7) Erstelle das Capacitor Projekt

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 unter Windows warnt, dass CocoaPods nicht verfügbar ist. Das ist normal; der ios/ Ordner wird trotzdem erstellt und committet, und der Cloud-Build läuft pod install später.

Auf dem Emulator oder einem USB-Gerät ausführen:

bunx cap run android

WebView in Chrome debuggen unter chrome://inspect.

8) Android Release-Builds

keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleRelease

Die AAB befindet sich in android\app\build\outputs\bundle\release\. Für Teams ist es besser, den Keystore einmal in Capgo zu speichern und in der Cloud zu bauen; siehe Capgo Build für Android.

9) iOS von Windows aus mit Capgo Build

Xcode gibt es nur für macOS, daher erfolgt der iOS-Compile über die Mac-Infrastruktur von Capgo. Über dein Windows-Terminal:

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 sammelt deine Signing-Daten. Unter Windows wird der App Store Connect API Key manuell im Apple-Portal erstellt, gemäß der iOS-Build-Anleitung. Das Distribution-Zertifikat benötigt keinen Keychain Access: Erstelle den CSR und .p12 mit OpenSSL (winget install ShiningLight.OpenSSL.Light) oder über den browserbasierten iOS-Zertifikatsgenerator. Die Schritt-für-Schritt-Anleitung findest du in iOS-App unter Windows mit Capacitor und Capgo Build bauen.

Sobald der Build fertig ist, kann Capgo ihn zu TestFlight pushen, sodass du ihn Minuten später auf einem echten iPhone installieren kannst.

10) Web-Änderungen ohne Rebuild deployen

Sobald beide Stores live sind, nutze Capgo Live Updates für JavaScript-, HTML- und CSS-Änderungen:

bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production

Native Builds sind nur für Plugins, Berechtigungen und Capacitor Upgrades nötig.

Häufige Windows-Probleme

• running scripts is disabled on this system: Execution Policy. Siehe Schritt 1.
• SDK location not found: ANDROID_HOME nicht für das Terminal gesetzt, das Gradle ausführt. Starte das Terminal nach der Einstellung neu oder erstelle android\local.properties mit sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.
• Filename too long aus Git oder Gradle: Long Paths aktivieren, Schritt 6.
• Emulator hängt beim Booten: Hypervisor nicht aktiviert oder BIOS-Virtualisierung aus.
• gradlew: bad interpreter in der CI: gradlew was mit CRLF-Endungen committet wurde. Beheben Sie dies mit .gitattributes oben und renormieren.
• EPERM oder gesperrte Dateien während bun install: Defender oder ein laufender Gradle-Daemon hält Dateien gesperrt. Stoppen Sie den Daemon mit .\gradlew.bat --stop und fügen Sie die Ausnahmen hinzu.

Zusammenfassung

Windows deckt Android und den Web-Layer End-to-End ab. Für iOS generieren Sie das Projekt lokal, synchronisieren es und übergeben den ios/ Capgo Ordner an Capgo Build. Nutzen Sie Live Updates zusätzlich, und Ihr Windows-Team kann auf beide Stores deployen, ohne auch nur einen Mac im Büro zu haben. Wenn Sie eine Linux-Shell unter Windows bevorzugen, lesen Sie den Begleitguide zu der Nutzung von WSL2 für Capacitor Entwicklung.