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 Build Capgo.
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 Ubuntu
Reboot, buka Ubuntu, buat user Linux Anda. Update dan install dasar-dasarnya:
sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash
2) Simpan proyek di file system Linux
Buat proyek Anda di home Linux, bukan di /mnt/c:
mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install
Akses file dari tool Windows melalui \\wsl$\Ubuntu\home\you\dev\my-app. VS Code dengan ekstensi WSL membukanya langsung dengan code ..
Mengapa ini penting: akses lintas sistem file melalui /mnt/c lambat untuk ribuan file kecil di node_modules, dan inotify watchers yang digunakan Vite tidak memicu dengan andal untuk file di drive Windows.
3) Tentukan di mana Android SDK berada
Dua layout yang bisa bekerja:
Layout A (disarankan): SDK di Windows, Gradle di WSL2 menunjuk ke salinan SDK Linux. Install Android Studio di Windows untuk emulator dan tool GUI, dan 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 --licenses
Ya, ini menduplikasi beberapa ratus megabyte. Sebagai gantinya, Gradle berjalan dengan kecepatan 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 plus gradlew dari PowerShell pada file yang sama melalui \\wsl$. Ini berfungsi tetapi 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) Jembatani adb antara WSL2 dan Windows
Emulator dan ponsel USB terhubung ke Windows. Build Gradle WSL2 dan cap run android perlu terhubung ke perangkat tersebut. Jalankan satu server adb di Windows dan jadikan WSL2 sebagai klien.
Di Windows, jalankan server adb yang mendengarkan di semua antarmuka. Gunakan adb dari SDK Windows:
adb kill-server
adb -a -P 5037 nodaemon server
Biarkan jendela itu terbuka. Izinkan port 5037 melalui firewall Windows untuk adapter virtual WSL jika diminta.
Di WSL2, arahkan klien adb ke host Windows:
export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices
Emulator atau ponsel Anda sekarang muncul di dalam WSL2. Kedua biner adb harus memiliki versi mayor yang sama, jadi perbarui platform-tools di kedua sisi secara bersamaan.
Mirrored networking mempermudah proses ini
Di Windows 11 22H2 atau lebih baru, aktifkan mirrored networking agar WSL2 berbagi stack jaringan Windows. Buat atau edit %USERPROFILE%\.wslconfig:
[wsl2]
networkingMode=mirrored
Jalankan wsl --shutdown, buka ulang Ubuntu, lalu gunakan ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. IP host tidak lagi berubah setiap reboot, dan live reload juga jadi lebih sederhana.
Alternatif: teruskan perangkat USB ke WSL2
Jika Anda ingin adb 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-3
Lalu tambahkan aturan udev dari Panduan Linux di dalam WSL2. Ini tidak membantu untuk emulator, yang tetap berupa koneksi jaringan.
5) Jalankan aplikasinya
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 android
cap open android ingin Android Studio di mesin yang sama. Sebagai gantinya, buka android/ folder di Windows Android Studio melalui \\wsl$\Ubuntu\home\you\dev\my-app\android. Gradle bawaan Studio kemudian melakukan build di Windows sementara terminal Anda melakukan build di WSL2; keduanya berbagi file source yang sama.
6) Live reload lintas batas
Vite berjalan di WSL2, sementara aplikasi berjalan di emulator Windows atau ponsel. Emulator harus dapat mengakses dev server.
Jalankan Vite dengan bind ke semua interface:
bun run dev -- --host 0.0.0.0
Arahkan 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 mesin host. Dengan mirrored networking, port WSL2 terlihat di host Windows, sehingga alamat ini bisa menjangkau Vite. Tanpa mirrored networking, lakukan 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 USB, ganti URL dengan IP LAN Windows Anda dan izinkan port 5173 melalui firewall Windows. Jalankan bunx cap sync android setelah mengubah config, dan hapus server blok sebelum membangun release.
7) iOS dari WSL2 dengan Capgo Build
Xcode membutuhkan macOS, jadi WSL2 menangani semua proses hingga kompilasi native, dan Capgo mengerjakan 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 release
CLI mengunggah file yang sudah disiapkan ios/ proyek dan mengalirkan log kembali ke terminal WSL2 Anda. Material signing 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 berlaku untuk WSL2 tanpa perubahan.
8) Hindari build native untuk perubahan harian
Setelah kedua aplikasi ada di store, Live Updates Capgo push perubahan web dari WSL2 tanpa menyentuh Gradle atau Capgo Build:
bunx @capgo/cli@latest bundle upload --channel production
Masalah 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 WSL2. - Drift jam merusak autentikasi Apple API selama
build init: jam WSL2 bergeser setelah sleep. Jalankansudo hwclock -sdan coba lagi. cap open androidgagal: Studio ada di Windows. Buka folder dari Studio saja.
Ringkasan
WSL2 adalah tempat yang tepat untuk toolchain web Capacitor jika tim Anda hidup di bash. Biarkan emulator dan perangkat tetap di Windows, hubungkan dengan satu server adb, 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.