La maggior parte della documentazione Capacitor presuppone l'uso di un Mac. Se sviluppi su Windows, lo strato web e Android funzionano allo stesso modo, con alcune insidie specifiche di Windows su PowerShell, lunghezza dei path ed emulatore. iOS è l'unico elemento che Windows non può compilare, e la soluzione è una cloud macOS build.
Questa guida copre la configurazione completa su Windows 11, da una macchina vuota fino alla build Android su dispositivo e alla build iOS in TestFlight tramite Build Capgo.
Cosa funziona su Windows e cosa no
| Task | Windows |
|---|---|
| Sviluppo web, Vite, framework tooling | Sì |
cap add android, cap sync, build Gradle |
Sì |
| Emulatore Android | Sì, con Hyper-V o WHPX |
| Dispositivo Android fisico via USB | Sì |
| Remote debugging con Chrome DevTools | Sì |
cap add ios, cap sync ios (genera e copia) |
Sì, con un avviso di CocoaPods |
| Compila, firma e archivia iOS | No, serve macOS. Usa Capgo Build |
| Simulatore iOS | No |
| Safari Web Inspector per iOS WebView | No |
1) Installa Node o Bun
Usa winget da PowerShell:
winget install OpenJS.NodeJS.LTS
# Or Bun
winget install Oven-sh.Bun
Apri un nuovo terminale e conferma:
node --version
bun --version
Correggi l'execution policy di PowerShell
bunx cap, npx cap e la maggior parte degli shim CLI sono .ps1 script. Un Windows appena installato li blocca con running scripts is disabled on this system. Consenti gli script locali una volta:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
2) Installa JDK 21
Capacitor 7 e 8 richiedono JDK 21. Android Studio include il proprio JBR, ma un JDK di sistema evita sorprese quando esegui Gradle da terminale.
winget install Microsoft.OpenJDK.21
Imposta JAVA_HOME per il tuo utente. Da PowerShell:
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot", "User")
Adatta la cartella alla versione installata. Poi riavvia il terminale.
3) Installa Android Studio e il SDK
winget install Google.AndroidStudio
Avvia Android Studio e lascia che la procedura guidata installi SDK per C:\Users\<you>\AppData\Local\Android\Sdk. Poi imposta le variabili d'ambiente che Gradle e Capacitor cercano:
$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")
Apri il SDK Manager di Android Studio e installa la piattaforma corrispondente alla tua versione Capacitor: API 36 per Capacitor 8, API 35 per Capacitor 7.
4) Velocizzare l'emulatore
L'emulatore richiede la virtualizzazione hardware. Su Windows 11 l'emulatore usa la Windows Hypervisor Platform. Abilitala:
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
Riavvia. Se il Device Manager di Android Studio segnala ancora problemi di accelerazione, verifica che la virtualizzazione sia attiva nel BIOS o UEFI e che l'Isolamento core (Integrità della memoria) non la blocchi su CPU più vecchie.
Crea un dispositivo in Device Manager, oppure da terminale:
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) Debug USB su Windows
Abilita le Opzioni sviluppatore e il debug USB sul telefono. La maggior parte dei telefoni non richiede più driver, ma se adb devices rimane vuoto, installa il driver USB di Google tramite il SDK Manager (scheda SDK Tools) o il driver del produttore per i dispositivi Samsung.
adb devices
Accetta il prompt dell'impronta digitale sul telefono la prima volta.
6) Correzioni specifiche per progetti su Windows
Tre impostazioni per risparmiare ore su Windows:
Percorsi lunghi. Gradle e node_modules possono superare il limite di 260 caratteri. Abilita i percorsi lunghi con:
git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
Il secondo comando richiede PowerShell come amministratore.
Esclusioni di Defender. La scansione in tempo reale di node_modules, la cache di Gradle e la SDK di Android rallentano i build. Escludi queste cartelle da Windows Security o tramite PowerShell come amministratore:
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.gradle"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Android\Sdk"
Add-MpPreference -ExclusionPath "C:\dev"
Mantieni i progetti in un percorso breve come C:\dev\my-app, non in Documenti sincronizzati con OneDrive.
Fine riga. Quella di Gradle gradlew shell script must keep LF endings or Linux CI breaks. Add a .gitattributes:
*.sh text eol=lf
gradlew text eol=lf
7) Crea il progetto 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 su Windows segnala che CocoaPods non è disponibile. È normale; la ios/ cartella viene comunque generata e committata, e la build cloud viene eseguita pod install più tardi.
Esegui sull'emulatore o su un dispositivo USB:
bunx cap run android
Debugga la WebView in Chrome su chrome://inspect.
8) Build di rilascio Android
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleRelease
L'AAB si trova in android\app\build\outputs\bundle\release\. Per un team, è meglio salvare il keystore una volta sola in Capgo e farlo buildare in cloud; vedi Capgo Build per Android.
9) iOS da Windows con Capgo Build
Xcode è disponibile solo su macOS, quindi la compilazione iOS avviene sull'infrastruttura Mac di Capgo. Dal tuo terminale 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 raccoglie i tuoi certificati di firma. Su Windows la chiave API di App Store Connect va creata manualmente nel portale Apple, seguendo la Guida build iOS. Il certificato di distribuzione non richiede Keychain Access: crea il CSR e .p12 con OpenSSL (winget install ShiningLight.OpenSSL.Light) o quella basata sul browser Generatore di certificati iOS. La guida passo dopo passo è in Build un'app iOS da Windows con Capacitor e Capgo Build.
Al termine della build, Capgo può caricarla su TestFlight, così potrai installarla su un iPhone reale dopo pochi minuti.
10) Distribuisci modifiche web senza rebuild
Con entrambi gli store attivi, usa Live Updates di Capgo per modifiche a JavaScript, HTML e CSS:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
I Native Build servono solo per plugin, permessi e aggiornamenti di Capacitor.
Problemi comuni su Windows
running scripts is disabled on this system: execution policy. Vedi il passaggio 1.SDK location not found:ANDROID_HOMEnon impostata per il terminale che esegue Gradle. Riavvia il terminale dopo l'impostazione, o creaandroid\local.propertiesconsdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.Filename too longda Git o Gradle: abilita i percorsi lunghi, passaggio 6.- Emulatore bloccato all'avvio: hypervisor non abilitato o virtualizzazione BIOS disattivata.
gradlew: bad interpreterin CI:gradlewè stato committato con finali CRLF. Correggi con il.gitattributessopra e rinormalizza.EPERMo file bloccati durantebun install: Defender o un daemon Gradle attivo stanno trattenendo i file. Ferma il daemon con.\gradlew.bat --stope aggiungi le esclusioni.
Riassunto
Windows copre Android e il web layer end-to-end. Per iOS, genera il progetto localmente, sincronizza e passa la cartella ios/ a Capgo Build. Aggiungi Live Updates e il tuo team Windows rilascerà su entrambi gli store senza un singolo Mac in ufficio. Se preferisci una shell Linux su Windows, leggi la guida su come usare WSL2 per lo sviluppo con Capacitor.