WSL2 memberi developer Windows shell Linux asli, yang penting saat script, Dockerfile, dan CI tim Anda semuanya mengandalkan bash. Untuk Capacitor, ini bekerja baik, dengan satu aturan: pertahankan toolchain web di WSL2 dan biarkan emulator Android, perangkat USB, serta Android Studio di Windows. Lalu hubungkan keduanya dengan adb.
Panduan ini menunjukkan setup tersebut, detail networking yang sering bikin orang kesulitan, dan bagaimana iOS masuk melalui Capgo Build.
Kapan WSL2 layak digunakan
Gunakan WSL2 jika:
- Repo Anda punya bash scripts, Makefiles, atau Husky hooks yang error di PowerShell.
- Anda menjalankan Docker images yang sama secara lokal dan di CI.
- Anda ingin layout Linux
node_modulesagar lockfiles sesuai dengan Linux CI Anda.
Lewati WSL2 jika Anda hanya butuh Android Studio dan terminal. Panduan Windows native lebih simpel dalam kasus tersebut.
1) Install WSL2 dan distro
Dari PowerShell dengan akses administrator:
wsl --install -d UbuntuReboot, buka Ubuntu, buat user Linux Anda. Update dan install hal-hal dasar:
sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash2) Simpan project di dalam file system Linux
Buat project Anda di dalam home Linux, jangan di /mnt/c:
mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun installAkses file dari tools Windows melalui \\wsl$\Ubuntu\home\you\dev\my-app. VS Code dengan ekstensi WSL membukanya langsung dengan code ..
Mengapa ini penting: akses lintas file system melalui /mnt/c sangat lambat untuk ribuan file kecil di node_modules, dan inotify watcher yang digunakan Vite tidak berjalan stabil untuk file di drive Windows.
3) Tentukan di mana SDK Android berada
Dua layout yang bisa digunakan:
Layout A (rekomendasi): SDK di Windows, Gradle di WSL2 yang mengarah ke salinan SDK Linux. Install Android Studio di Windows untuk emulator dan tools GUI, lalu install SDK command line terpisah di dalam WSL2 untuk Gradle:
mkdir -p ~/Android/Sdk/cmdline-tools && cd ~/Android/Sdk/cmdline-tools
# download commandlinetools-linux-*.zip from the Android developer site
unzip commandlinetools-linux-*.zip && mv cmdline-tools latest
echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools' >> ~/.bashrc
source ~/.bashrc
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
sdkmanager --licensesYa, ini memakan beberapa ratus megabyte. Sebagai gantinya, Gradle berjalan secepat Linux dan tidak pernah menyentuh /mnt/c.
Layout B: semuanya di Windows, WSL2 hanya untuk web build. You run bun run build di WSL2 dan cap sync ditambah gradlew dari PowerShell pada file yang sama melalui \\wsl$. Ini berfungsi tapi lebih lambat dan mencampur dua shell. Pilih ini hanya jika Anda tidak bisa menginstal apa pun di WSL2.
Sisa panduan ini mengasumsikan Layout A.
4) Bridge adb antara WSL2 dan Windows
Emulator dan ponsel USB terhubung ke Windows. Build Gradle di WSL2 dan cap run android perlu menjangkau mereka. Biarkan satu server adb tetap berjalan di Windows dan jadikan WSL2 sebagai client-nya.
Di Windows, jalankan adb server yang mendengarkan di semua interface. Gunakan adb dari Windows SDK:
adb kill-server
adb -a -P 5037 nodaemon serverBiarkan jendela tersebut tetap terbuka. Izinkan port 5037 melalui Windows firewall untuk adapter virtual WSL jika diminta.
Di WSL2, arahkan adb client ke host Windows:
export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devicesEmulator atau ponsel Anda sekarang muncul di dalam WSL2. Kedua binary adb harus memiliki versi major yang sama, jadi update platform-tools di kedua sisi secara bersamaan.
Mirrored networking mempermudah hal ini
Pada Windows 11 22H2 atau yang lebih baru, aktifkan mirrored networking agar WSL2 berbagi network stack Windows. Buat atau edit %USERPROFILE%\.wslconfig:
[wsl2]
networkingMode=mirroredJalankan wsl --shutdown, buka kembali Ubuntu, lalu gunakan ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. IP host tidak lagi berubah setiap kali reboot, dan live reload juga jadi lebih simpel.
Alternatif: pass perangkat USB ke WSL2
Jika Anda ingin adb berjalan sepenuhnya di dalam WSL2 untuk ponsel fisik, gunakan usbipd-win:
winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3Kemudian tambahkan udev rule dari Panduan Linux di dalam WSL2. Ini tidak membantu untuk emulator, yang tetap menggunakan koneksi jaringan.
5) Jalankan aplikasi
Dengan adb bridged, Capacitor bekerja seperti di Linux:
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
bunx cap run androidcap open android membutuhkan Android Studio di mesin yang sama. Sebagai gantinya, buka android/ folder di Windows Android Studio melalui \\wsl$\Ubuntu\home\you\dev\my-app\androidGradle bawaan Studio kemudian melakukan build di Windows sementara terminal Anda melakukan build di WSL2; keduanya berbagi file source yang sama.
6) Live reload lintas boundary
Vite berjalan di WSL2, sementara aplikasi berjalan di emulator Windows atau ponsel. Emulator harus dapat mengakses dev server.
Jalankan Vite yang terikat ke semua interface:
bun run dev -- --host 0.0.0.0Arahkan Capacitor ke sana di capacitor.config.ts:
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'dist',
server: {
url: 'http://10.0.2.2:5173',
cleartext: true,
},
};10.0.2.2 adalah alias emulator untuk host machine. Dengan mirrored networking, port WSL2 terlihat di host Windows, sehingga alamat ini bisa menjangkau Vite. Tanpa mirrored networking, forward port di Windows terlebih dahulu:
netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)Untuk ponsel via USB, ganti URL dengan IP LAN Windows Anda dan izinkan port 5173 di firewall Windows. Jalankan bunx cap sync android setelah mengubah konfigurasi, dan hapus server block sebelum melakukan build release.
7) iOS dari WSL2 dengan Capgo Build
Xcode butuh macOS, jadi WSL2 menangani semuanya hingga native compile dan Capgo melakukan sisanya:
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 releaseCLI mengunggah file yang telah disiapkan ios/ project yang sudah siap dan streaming logs kembali ke terminal WSL2 Anda. Signing material dibuat tanpa Mac, menggunakan OpenSSL atau iOS certificate generator kami. Detail lengkap ada di Build aplikasi iOS dari Linux dengan Capacitor dan Capgo Build, yang tetap berlaku sama untuk WSL2.
8) Hindari native build untuk perubahan harian
Setelah kedua aplikasi ada di store, Capgo Live Updates push perubahan web dari WSL2 tanpa menyentuh Gradle atau Capgo Build:
bunx @capgo/cli@latest bundle upload --channel productionMasalah umum WSL2
adb: device offlineatau list kosong di WSL2: Windows adb server tidak berjalan dengan-a, atau versinya berbeda. Restart dan bandingkanadb versiondi kedua sisi.- IP host berubah setelah reboot: wajar jika tidak pakai mirrored networking. Masukkan
WSL_HOSTexport di~/.bashrcagar dihitung ulang, atau beralih ke mirrored mode. - Vite tidak mendeteksi perubahan file: proyek berada di bawah
/mnt/c. Pindahkan ke home Linux. - Gradle sangat lambat: penyebab sama, atau cache Gradle ada di
/mnt/c. Simpan~/.gradledi dalam WSL2. - Clock drift merusak autentikasi Apple API saat
build init: jam WSL2 meleset setelah sleep. Jalankansudo hwclock -sdan coba lagi. cap open androidgagal: Studio ada di Windows. Buka folder langsung dari Studio.
Ringkasan
WSL2 adalah lingkungan yang ideal untuk Capacitor web toolchain jika tim Anda terbiasa menggunakan bash. Biarkan emulator dan perangkat tetap di Windows, hubungkan dengan satu adb server, simpan file di sistem file Linux, dan biarkan Capgo Build menangani kompilasi iOS. Hasilnya adalah workflow Linux di laptop Windows yang tetap bisa rilis ke kedua app store.
