Capacitor Développer sur Windows : le guide complet de configuration

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

1) Installez 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 pour C:\Users\<you>\AppData\Local\Android\Sdk. Ensuite, configurez les variables d'environnement Gradle et Capacitor suivantes :

$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 de 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 votre BIOS ou UEFI et que l'isolation du noyau (intégrité de la mémoire) ne la bloque pas sur les processeurs plus anciens.

Créez un appareil dans le Device Manager, ou via 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 sur Windows

Activez les options développeur et le débogage USB sur le téléphone. La plupart des téléphones n'ont plus besoin de driver, mais si adb devices reste vide, installez le driver USB de Google via le SDK Manager (onglet SDK Tools) ou le driver du fabricant pour les appareils Samsung.

adb devices

Acceptez le prompt d'empreinte digitale sur le téléphone la première fois.

6) Correctifs spécifiques à Windows

Trois réglages pour gagner des heures sur Windows :

Les chemins longs. Gradle et node_modules peuvent dépasser la limite de 260 caractères. Activez les chemins longs via :

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.

Les exclusions Defender. L'analyse en temps réel de node_modules, le cache Gradle et le SDK Android ralentissent nettement les builds. Excluez ces dossiers dans la Sécurité Windows, ou via 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 comme C:\dev\my-app, not under OneDrive-synced Documents.

Les fins de ligne. Celles de Gradle gradlew le shell script doit garder les fins de ligne LF, sinon le CI Linux plante. 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 indique que CocoaPods n'est pas disponible. C'est normal ; le ios/ dossier est quand même généré et commit, et le cloud build s'exécute pod install plus tard.

Exécuter sur l'émulateur ou un appareil USB :

bunx cap run android

Déboguer 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, il vaut mieux sauvegarder le keystore une fois dans Capgo et le build dans le cloud ; voir Capgo Build pour Android.

9) iOS depuis Windows avec Capgo Build

Xcode est réservé à macOS, la compilation iOS s'effectue 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 récupère vos éléments de signature. Sur Windows, la clé API pour App Store Connect est créée manuellement sur le portail Apple, en suivant la Guide de build iOS. Le certificat de distribution n'a pas besoin de l'accès au trousseau : créez le CSR et .p12 avec OpenSSL (winget install ShiningLight.OpenSSL.Light) ou via l'outil Générateur de certificats iOSLe guide étape par étape est dans Compiler une app iOS depuis Windows avec Capacitor et Capgo Build.

Une fois le build terminé, Capgo peut le pousser sur TestFlight pour que vous puissiez l'installer sur un iPhone réel quelques minutes plus tard.

10) Déployer des modifications web sans recompiler

Une fois les deux stores en ligne, utilisez Capgo Live Updates 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_HOME n'est pas défini pour le terminal qui exécute Gradle. Redémarrez le terminal après l'avoir défini, ou créez android\local.properties par sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.
• Filename too long depuis 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 interpreter en CI: gradlew a été commit avec des fins de ligne CRLF. Corrigez avec le .gitattributes ci-dessus et renormalisez.
• EPERM ou des fichiers verrouillés pendant bun install: Defender ou un daemon Gradle en cours qui verrouille des fichiers. Arrêtez le daemon avec .\gradlew.bat --stop et 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.