La documentation Capacitor suppose le plus souvent un Mac. Si vous développez sur Windows, la couche web et Android fonctionnent de la même manière, avec quelques pièges propres à Windows autour de PowerShell, de la longueur des chemins et de l'émulateur. iOS est la seule partie que Windows ne peut pas compiler, et la solution est un build cloud macOS.
Ce guide est la configuration complète pour Windows 11, d'une machine vierge jusqu'à un build Android sur un appareil et un build iOS dans TestFlight via Build Capgo.
Ce qui fonctionne sur Windows et ce qui ne fonctionne pas
| Tâche | Windows |
|---|---|
| Développement web, Vite, outils du framework | Oui |
cap add android, cap sync, builds Gradle |
Oui |
| Émulateur Android | Oui, avec Hyper-V ou WHPX |
| Appareil Android physique via USB | Oui |
| Débogage distant avec Chrome DevTools | Oui |
cap add ios, cap sync ios (générer et copier) |
Oui, avec un avertissement CocoaPods |
| Compiler, signer et archiver iOS | Non, nécessite macOS. Utilisez Capgo Build |
| Simulateur iOS | Non |
| Safari Web Inspector pour WebView iOS | Non |
1) Installer Node ou Bun
Utiliser winget depuis PowerShell :
winget install OpenJS.NodeJS.LTS
# Or Bun
winget install Oven-sh.Bun
Ouvrez un nouveau terminal et confirmez :
node --version
bun --version
Corrigez la politique d'exécution PowerShell
bunx cap, npx cap et la plupart des shims CLI sont des .ps1 scripts. Un Windows fraîchement installé les bloque avec running scripts is disabled on this system. Autorisez les scripts locaux une fois :
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
2) Installez JDK 21
Capacitor 7 et 8 nécessitent JDK 21. Android Studio inclut son propre JBR, mais un JDK système évite les surprises quand vous lancez Gradle depuis un terminal.
winget install Microsoft.OpenJDK.21
Définissez JAVA_HOME pour votre utilisateur. Depuis PowerShell :
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot", "User")
Adaptez le dossier à la version installée. Redémarrez ensuite le terminal.
3) Installez Android Studio et le SDK
winget install Google.AndroidStudio
Lancez Android Studio et laissez l’assistant d’installation installer le SDK vers C:\Users\<you>\AppData\Local\Android\Sdk. Définissez ensuite les variables d’environnement que Gradle et Capacitor recherchent :
$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")
Ouvrez le SDK Manager d’Android Studio et installez la plateforme correspondant à votre version Capacitor : API 36 pour Capacitor 8, API 35 pour Capacitor 7.
4) Accélérer l’émulateur
L’émulateur nécessite la virtualisation matérielle. Sur Windows 11, l’émulateur utilise la Windows Hypervisor Platform. Activez-la :
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
Redémarrez. Si le Device Manager d’Android Studio signale toujours un problème d’accélération, vérifiez que la virtualisation est activée dans le BIOS ou l’UEFI et que l’Isolation du noyau (Intégrité de la mémoire) ne la bloque pas sur les anciens processeurs.
Créez un appareil dans le Device Manager, ou depuis un 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) Débogage USB sous Windows
Activez les options de développeur et le débogage USB sur le téléphone. La plupart des téléphones n’ont plus besoin de pilote, mais si adb devices reste vide, installez le pilote USB de Google via le SDK Manager (onglet SDK Tools) ou le pilote du fabricant pour les appareils Samsung.
adb devices
Acceptez la demande d’empreinte sur le téléphone la première fois.
6) Corrections spécifiques à Windows
Trois réglages qui font gagner des heures sur Windows :
Chemins longs. Gradle et node_modules peut dépasser la limite de 260 caractères. Activez les chemins longs une fois :
git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
La deuxième commande nécessite un PowerShell en mode administrateur.
Exclusions Defender. L'analyse en temps réel de node_modules, du cache Gradle et du SDK Android ralentit nettement les builds. Excluez ces dossiers dans la Sécurité Windows, ou depuis un PowerShell en mode administrateur :
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.gradle"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Android\Sdk"
Add-MpPreference -ExclusionPath "C:\dev"
Gardez vos projets dans un chemin court du type C:\dev\my-app, et non dans Documents synchronisé avec OneDrive.
Fins de ligne. de Gradle gradlew script shell doit conserver des fins de ligne LF, sinon la CI Linux échoue. Ajoutez un .gitattributes:
*.sh text eol=lf
gradlew text eol=lf
7) Créer le projet Capacitor
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 sur Windows avertit que CocoaPods n'est pas disponible. C'est normal ; le ios/ dossier est tout de même généré et commité, et le build cloud s'exécute pod install ensuite.
Exécuter sur l'émulateur ou un appareil USB :
bunx cap run android
Débuguez la WebView dans Chrome sur chrome://inspect.
8) Builds de release Android
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleRelease
L’AAB se trouve dans android\app\build\outputs\bundle\release\. Pour une équipe, mieux vaut enregistrer le keystore une seule fois dans Capgo et compiler dans le cloud ; voir Capgo Build pour Android.
9) iOS depuis Windows avec Capgo Build
Xcode n’existe que sur macOS, la compilation iOS se fait donc sur l’infrastructure Mac de Capgo. Depuis votre terminal Windows :
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 collecte vos éléments de signature. Sur Windows, la clé API d’App Store Connect est créée manuellement dans le portail Apple, en suivant le Guide de build iOS. Le certificat de distribution n’a pas besoin de Keychain Access : créez le CSR et .p12 avec OpenSSL (winget install ShiningLight.OpenSSL.Light) ou via le navigateur Générateur de certificats iOS. Le pas à pas est dans Compiler une app iOS depuis Windows avec Capacitor et Capgo Build.
Une fois le build terminé, Capgo peut l’envoyer sur TestFlight pour que vous l’installiez sur un vrai iPhone quelques minutes plus tard.
10) Déployer des modifications web sans recompiler
Avec les deux stores en ligne, utilisez Live Updates Capgo pour les modifications JavaScript, HTML et CSS :
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
Les rebuilds natifs ne sont requis que pour les plugins, les permissions et les mises à niveau Capacitor.
Problèmes courants sur Windows
running scripts is disabled on this system: la stratégie d'exécution. Voir l'étape 1.SDK location not found:ANDROID_HOMEn'est pas défini pour le terminal qui exécute Gradle. Redémarrez le terminal après l'avoir défini, ou créezandroid\local.propertiesparsdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.Filename too longdepuis Git ou Gradle : activez les chemins longs, étape 6.- Émulateur bloqué au démarrage : l'hyperviseur n'est pas activé ou la virtualisation BIOS est désactivée.
gradlew: bad interpreteren CI:gradlewa été commit avec des fins de ligne CRLF. Corrigez avec le.gitattributesci-dessus et renormalisez.EPERMou des fichiers verrouillés pendantbun install: Defender ou un daemon Gradle en cours qui verrouille des fichiers. Arrêtez le daemon avec.\gradlew.bat --stopet ajoutez les exclusions.
Résumé
Windows couvre Android et la couche web de bout en bout. Pour iOS, générez le projet localement, synchronisez, puis transmettez le ios/ dossier à Capgo Build. Ajoutez Live Updates par-dessus et votre équipe Windows déploie sur les deux stores sans un seul Mac au bureau. Si vous préférez un shell Linux sur Windows, lisez le guide compagnon sur l'utilisation de WSL2 pour le développement Capacitor.