Sebagian besar dokumentasi Capacitor mengasumsikan penggunaan Mac. Jika Anda mengembangkan di Windows, lapisan web dan Android bekerja sama, dengan beberapa jebakan spesifik Windows terkait PowerShell, panjang path, dan emulator. iOS adalah satu-satunya bagian yang tidak dapat dikompilasi di Windows, dan solusinya adalah build macOS di cloud.
Panduan ini adalah setup lengkap Windows 11, dari mesin kosong hingga build Android di perangkat dan build iOS di TestFlight melalui Build Capgo.
Apa yang jalan dan tidak jalan di Windows
| Tugas | Windows |
|---|---|
| Pengembangan web, Vite, tooling framework | Ya |
cap add android, cap sync, build Gradle |
Ya |
| emulator Android | Bisa, dengan Hyper-V atau WHPX |
| Perangkat Android fisik via USB | Ya |
| Remote debugging Chrome DevTools | Ya |
cap add ios, cap sync ios (generate dan salin) |
Ya, dengan peringatan CocoaPods |
| Kompilasi, tanda tangan, arsipkan iOS | Tidak, butuh macOS. Gunakan Capgo Build |
| Simulator iOS | Tidak |
| Safari Web Inspector untuk iOS WebView | Tidak |
1) Install Node atau Bun
Gunakan winget dari PowerShell:
winget install OpenJS.NodeJS.LTS
# Or Bun
winget install Oven-sh.Bun
Buka terminal baru dan pastikan:
node --version
bun --version
Perbaiki PowerShell execution policy
bunx cap, npx cap dan sebagian besar CLI shims adalah .ps1 skrip. Windows yang baru diinstal memblokirnya dengan running scripts is disabled on this system. Izinkan skrip lokal sekali:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
2) Instal JDK 21
Capacitor 7 dan 8 membutuhkan JDK 21. Android Studio menyertakan JBR sendiri, tetapi JDK sistem menghindari kejutan saat menjalankan Gradle dari terminal.
winget install Microsoft.OpenJDK.21
Atur JAVA_HOME untuk pengguna Anda. Dari PowerShell:
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot", "User")
Sesuaikan folder dengan versi yang Anda instal. Restart terminal setelahnya.
3) Install Android Studio dan SDK
winget install Google.AndroidStudio
Buka Android Studio dan biarkan setup wizard menginstal SDK untuk C:\Users\<you>\AppData\Local\Android\Sdk. Lalu atur environment variable yang dicari Gradle dan Capacitor:
$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")
Buka SDK Manager di Android Studio dan instal platform yang sesuai dengan versi Capacitor: API 36 untuk Capacitor 8, API 35 untuk Capacitor 7.
4) Percepat emulator
Emulator membutuhkan virtualisasi hardware. Pada Windows 11, emulator menggunakan Windows Hypervisor Platform. Aktifkan fitur ini:
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
Reboot. Jika Device Manager di Android Studio masih memperingatkan soal akselerasi, pastikan virtualisasi sudah aktif di BIOS atau UEFI dan Core Isolation (Memory Integrity) tidak memblokirnya di CPU lama.
Buat device di Device Manager, atau dari 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) USB debugging di Windows
Aktifkan Developer options dan USB debugging di ponsel. Kebanyakan ponsel tidak butuh driver lagi, tapi jika adb devices tetap kosong, instal USB driver Google lewat SDK Manager (tab SDK Tools) atau driver vendor untuk perangkat Samsung.
adb devices
Terima prompt fingerprint di ponsel saat pertama kali.
6) Perbaikan proyek khusus Windows
Tiga pengaturan menghemat waktu di Windows:
Path panjang. Gradle dan node_modules dapat melebihi batas 260 karakter. Aktifkan jalur panjang sekali:
git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
Perintah kedua membutuhkan PowerShell dengan hak akses tinggi.
Pengecualian Defender. Pemindaian real-time dari node_modules, cache Gradle, dan Android SDK memperlambat build secara signifikan. Kecualikan folder tersebut di Windows Security, atau dari PowerShell dengan hak akses tinggi:
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.gradle"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Android\Sdk"
Add-MpPreference -ExclusionPath "C:\dev"
Simpan proyek Anda di jalur pendek seperti C:\dev\my-app, bukan di bawah Documents yang disinkronkan OneDrive.
Akhir baris. skrip shell gradlew Gradle harus mempertahankan akhir baris LF atau CI Linux akan rusak. Tambahkan .gitattributes:
*.sh text eol=lf
gradlew text eol=lf
7) Buat proyek 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 di Windows memperingatkan bahwa CocoaPods tidak tersedia. Itu wajar; ios/ folder tetap dibuat dan di-commit, dan cloud build dijalankan pod install nanti.
Jalankan di emulator atau perangkat USB:
bunx cap run android
Debug WebView di Chrome pada chrome://inspect.
8) Build rilis Android
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleRelease
AAB ada di android\app\build\outputs\bundle\release\. Untuk tim, keystore sebaiknya disimpan sekali di Capgo dan di-build di cloud; lihat Capgo Build untuk Android.
9) iOS dari Windows dengan Capgo Build
Xcode hanya tersedia di macOS, jadi kompilasi iOS dilakukan di infrastruktur Mac Capgo. Dari terminal Windows Anda:
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 mengumpulkan materi signing Anda. Di Windows, key API App Store Connect dibuat secara manual di portal Apple, mengikuti Panduan build iOS. Sertifikat distribusi tidak perlu Keychain Access: buat CSR dan .p12 dengan OpenSSL (winget install ShiningLight.OpenSSL.Light) atau yang berbasis browser iOS certificate generator kami. Panduan langkah demi langkahnya ada di Build aplikasi iOS dari Windows dengan Capacitor dan Capgo Build.
Setelah build selesai, Capgo bisa push ke TestFlight, jadi beberapa menit kemudian Anda sudah bisa menginstalnya di iPhone asli.
10) Rilis perubahan web tanpa rebuild
Saat kedua store sudah live, gunakan Live Updates Capgo untuk perubahan JavaScript, HTML, dan CSS:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
Native rebuild hanya diperlukan untuk plugin, izin, dan upgrade Capacitor.
Masalah umum di Windows
running scripts is disabled on this system: execution policy. Lihat langkah 1.SDK location not found:ANDROID_HOMEbelum diatur untuk terminal yang menjalankan Gradle. Restart terminal setelah mengaturnya, atau buatandroid\local.propertiesdengansdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.Filename too longdari Git atau Gradle: aktifkan long paths, langkah 6.- Emulator macet saat boot: hypervisor tidak diaktifkan atau virtualisasi BIOS mati.
gradlew: bad interpreterdi CI:gradlewdi-commit dengan akhiran CRLF. Perbaiki dengan.gitattributesdi atas dan lakukan renormalize.EPERMatau file yang terkunci saatbun install: Defender atau Gradle daemon yang sedang berjalan menahan file. Hentikan daemon dengan.\gradlew.bat --stopdan tambahkan pengecualiannya.
Ringkasan
Windows mencakup Android dan layer web secara end-to-end. Untuk iOS, generate project secara lokal, sync, lalu serahkan folder ios/ ke Capgo Build. Tambahkan Live Updates di atasnya dan tim Windows Anda bisa rilis ke kedua store tanpa perlu satu pun Mac di kantor. Jika Anda lebih suka shell Linux di Windows, baca panduan pendamping tentang menggunakan WSL2 untuk pengembangan Capacitor.