Langsung ke konten utama

Capacitor Development dengan WSL2 di Windows

Jalankan toolchain web Capacitor Anda di dalam WSL2 sementara emulator Android dan perangkat tetap di Windows: adb bridging, mirrored networking, performa file system, live reload, dan build iOS dengan Capgo Build.

Ilustrasi blog Capacitor development dengan WSL2 di Windows Capgo

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_modules agar 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 offline atau list kosong di WSL2: Windows adb server tidak berjalan dengan -a, atau versinya berbeda. Restart dan bandingkan adb version di kedua sisi.
  • IP host berubah setelah reboot: wajar jika tidak pakai mirrored networking. Masukkan WSL_HOST export di ~/.bashrc agar 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 ~/.gradle di WSL2.
  • Drift jam merusak autentikasi Apple API selama build init: jam WSL2 bergeser setelah sleep. Jalankan sudo hwclock -s dan coba lagi.
  • cap open android gagal: 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.

Live updates untuk aplikasi Capacitor

Saat bug web-layer sudah live, kirim perbaikannya lewat Capgo alih-alih menunggu berhari-hari untuk persetujuan app store. Pengguna mendapat update di background, sementara perubahan native tetap mengikuti jalur review normal.

Terbaru dari Blog kami

Capgo memberikan insight terbaik yang Anda butuhkan untuk membuat aplikasi mobile yang benar-benar profesional.