Aller au contenu principal

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

Configurer Capacitor sur Windows 11 : Node ou Bun, JDK 21, Android Studio et l'émulateur, le débogage USB, les correctifs PowerShell, les problèmes de chemins longs et les builds iOS sans Mac via Capgo Build.

Guide de configuration du développement Capacitor sur Windows Capgo illustration du blog

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_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.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.