La maggior parte della documentazione Capacitor presuppone l'uso di un Mac. Se sviluppi su Windows, il web layer e Android funzionano allo stesso modo, con qualche intoppo specifico legato a PowerShell, lunghezza dei path ed emulatore. iOS è l'unico elemento che Windows non può compilare: la soluzione è una build macOS in cloud.
Questa guida copre il setup completo 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, tooling per framework | 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.BunApri un nuovo terminale e conferma:
node --version
bun --versionCorreggi 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 RemoteSigned2) 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.21Imposta 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.AndroidStudioAvvia 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 HypervisorPlatformRiavvia. 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 pixel85) 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 devicesAccetta 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 così:
git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -ForceIl secondo comando richiede PowerShell con privilegi di amministratore.
Esclusioni di Defender. La scansione in tempo reale di node_modules, la cache di Gradle e la cartella 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 lo shell script deve mantenere gli ending LF o la CI su Linux si romperà. Aggiungi un .gitattributes:
*.sh text eol=lf
gradlew text eol=lf7) 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 ioscap add ios su Windows avvisa che CocoaPods non è disponibile. È normale; la ios/ cartella viene comunque generata e committata, e la cloud build viene eseguita pod install later.
Esegui sull'emulatore o su un dispositivo USB:
bunx cap run androidDebugga 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 bundleReleaseL'AAB si trova in android\app\build\outputs\bundle\release\. Per un team, è meglio salvare il keystore una volta sola in Capgo e 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 releasebuild init raccoglie i tuoi dati di firma. Su Windows, la chiave API di App Store Connect va creata manualmente nel portale Apple, seguendo il 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 via browser. La guida passo-passo è in Build di 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 rebuildare
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 productionI Native rebuild sono necessari solo per plugin, permessi e aggiornamenti Capacitor.
Problemi comuni su Windows
running scripts is disabled on this system: execution policy. Vedi il punto 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 (long paths), punto 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.
