Can I run the Android emulator inside WSL2?

Technically possible but not recommended. WSL2 has no nested virtualization by default and no GPU passthrough for the emulator. Run the emulator on Windows and connect to it from WSL2 by pointing the WSL adb client at the Windows adb server.

How do I use adb from WSL2 with a phone plugged into Windows?

Either forward the USB device into WSL2 with usbipd-win, or keep adb on Windows and set ADB_SERVER_SOCKET in WSL2 to the Windows host IP on port 5037. The second option is simpler and also works for the emulator.

Where should my Capacitor project live, in WSL2 or on the Windows drive?

Inside the WSL2 file system, for example /home/you/dev. Projects under /mnt/c are several times slower for node_modules and Gradle, and file watchers for live reload often miss changes there.

Can I build iOS from WSL2?

Not locally, since Xcode needs macOS. WSL2 runs the Capacitor CLI and cap sync ios fine, then Capgo Build compiles and signs the ios/ project in the cloud and can submit to TestFlight.

Windows에서 WSL2로 Capacitor 개발

WSL2는 Windows 개발자에게 실제 Linux 쉘을 제공합니다. 팀의 스크립트, Dockerfile, CI가 모두 bash를 기반으로 한다면 이는 매우 중요합니다. Capacitor에서도 한 가지 규칙만 지키면 잘 작동합니다. 웹 툴체인은 WSL2에 두고, Android 에뮬레이터, USB 기기, Android Studio는 Windows에 두는 것입니다. 그 다음 adb로 두 환경을 연결하세요.

이 가이드는 환경 설정 방법과 많은 이들이 어려워하는 네트워킹 세부 사항, 그리고 iOS가 어떻게 포함되는지 설명합니다. Capgo 빌드.

WSL2를 사용해야 하는 경우

다음과 같은 상황에서는 WSL2를 사용하세요:

레포지토리에 PowerShell에서 실행되지 않는 bash 스크립트, Makefile 또는 Husky hook이 있는 경우.
로컬과 CI 환경에서 동일한 Docker 이미지를 실행하는 경우.
Linux 환경을 선호하여 node_modules lockfile을 Linux CI와 일치시키고 싶은 경우.

Android Studio와 터미널만 필요하다면 WSL2는 건너뛰셔도 됩니다. 그럴 땐 Windows 네이티브 가이드를 따르는 것이 더 간단합니다.

1) WSL2 및 배포판 설치

관리자 권한의 PowerShell에서:

wsl --install -d Ubuntu

재부팅 후 Ubuntu를 열고 Linux 사용자를 생성하세요. 기본 패키지를 업데이트하고 설치합니다:

sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash

2) 프로젝트를 Linux 파일 시스템에 유지하세요

프로젝트를 Windows 경로가 아닌 Linux 홈 디렉토리 아래에 생성하세요. /mnt/c:

mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install

Windows 도구를 통해 파일을 액세스하려면 \\wsl$\Ubuntu\home\you\dev\my-app. VS Code에서 WSL 확장을 사용하면 Code를 직접 열 수 있습니다. code ..

Why this matters: cross-file-system access through /mnt/c 수천 개의 작은 파일들을 처리할 때 속도가 느려집니다 node_modules매우 느리며, Vite가 사용하는 inotify watcher가 Windows 드라이브의 파일에 대해 안정적으로 작동하지 않습니다.

3) Android SDK 위치를 결정하세요

두 가지 권장 레이아웃:

레이아웃 A (권장): Windows에 SDK를 설치하고, WSL2의 Gradle이 Linux의 SDK 복사본을 가리키도록 설정합니다. 에뮬레이터와 GUI 도구 사용을 위해 Windows에 Android Studio를 설치하고, Gradle 실행을 위해 WSL2 내부에 별도의 CLI SDK를 설치하세요:

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

네, 수백 메가바이트 정도 중복됩니다. 하지만 그 대가로 Gradle이 Linux 수준의 속도로 실행되며, /mnt/c.

레이아웃 B: 모든 것을 Windows에서 처리하고, WSL2는 웹 빌드용으로만 사용합니다. 다음 명령어를 실행합니다: bun run build 를 WSL2에서 실행하고, cap sync 및 gradlew PowerShell에서 동일한 파일에 대해 실행합니다. \\wsl$작동은 하지만 속도가 느리고 두 개의 셸이 섞이게 됩니다. WSL2에 아무것도 설치할 수 없는 경우에만 이 방식을 선택하세요.

이 가이드의 나머지 내용은 레이아웃 A를 기준으로 설명합니다.

4) WSL2와 Windows 간의 adb 브릿지 설정

에뮬레이터와 USB 연결된 폰은 Windows에 연결되어 있습니다. WSL2의 Gradle 빌드와 cap run android 이 여기에 접근해야 합니다. Windows에서 단일 adb 서버를 실행하고 WSL2를 클라이언트로 사용하세요.

Windows에서 모든 인터페이스를 리스닝하는 adb 서버를 시작합니다. Windows SDK의 adb를 사용하세요:

adb kill-server
adb -a -P 5037 nodaemon server

해당 창을 그대로 두세요. Windows 방화벽에서 WSL 가상 어댑터의 5037 포트 허용 메시지가 뜨면 허용해 주세요.

WSL2에서 adb 클라이언트가 Windows 호스트를 가리키도록 설정합니다:

export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices

이제 WSL2 내부에서 에뮬레이터나 연결된 기기가 나타납니다. 두 adb 바이너리의 메이저 버전이 일치해야 하므로, platform-tools 양쪽 모두 동시에 업데이트해야 합니다.

Mirrored networking을 사용하면 이 과정이 훨씬 간단해집니다.

Windows 11 22H2 이상 버전에서는 mirrored networking을 활성화하여 WSL2가 Windows 네트워크 스택을 공유하게 할 수 있습니다. .wslconfig 파일을 생성하거나 수정하고, %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

실행 wsl --shutdownUbuntu를 다시 연 다음 ADB_SERVER_SOCKET=tcp:127.0.0.1:5037를 사용하세요. 이제 재부팅할 때마다 호스트 IP가 바뀌지 않으며, live reload도 더 간편해집니다.

대안: WSL2로 USB 장치 연결하기

실제 기기를 위해 adb를 WSL2 내부에서 완전히 사용하고 싶다면 usbipd-win을 사용하세요:

winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3

그 다음 다음의 udev 규칙을 추가하세요: Linux 가이드 WSL2 내부에서 실행됩니다. 다만 네트워크 연결 상태를 유지해야 하는 에뮬레이터에는 적용되지 않습니다.

5) 앱 실행

adb 브릿지를 연결하면, Capacitor는 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 동일한 머신에 Android Studio가 필요합니다. 대신, android/ Windows의 Android Studio에서 해당 폴더를 \\wsl$\Ubuntu\home\you\dev\my-app\android열어주세요. Studio에 포함된 Gradle은 Windows에서 빌드하고, 터미널은 WSL2에서 빌드합니다. 두 환경은 동일한 소스 파일을 공유합니다.

6) 경계를 넘나드는 Live reload

Vite는 WSL2에서 실행되고, 앱은 Windows 에뮬레이터나 실제 기기에서 실행됩니다. 에뮬레이터가 개발 서버에 접속할 수 있어야 합니다.

모든 인터페이스에 바인딩된 Vite를 실행하세요:

bun run dev -- --host 0.0.0.0

WSL2 내의 Capacitor 설정을 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 는 호스트 머신에 대한 에뮬레이터의 별칭입니다. Mirrored networking을 사용하면 WSL2 포트가 Windows 호스트에서 보이므로 이 주소로 Vite에 접속할 수 있습니다. Mirrored networking을 사용하지 않는다면, 먼저 Windows에서 포트를 포워딩하세요:

netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)

USB로 연결된 폰을 사용하려면 URL을 Windows LAN IP로 변경하고 Windows 방화벽에서 5173 포트를 허용하세요. 그 다음 bunx cap sync android 설정을 변경한 후 실행하고, 릴리스 빌드 전에 server 를 제거하세요.

7) Capgo Build를 이용한 WSL2에서의 iOS 빌드

Xcode는 macOS가 필요하므로, WSL2는 네이티브 컴파일 직전 단계까지 처리하며 나머지는 Capgo가 담당합니다:

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가 준비된 ios/ 프로젝트를 upload하고 로그를 WSL2 터미널로 스트리밍합니다. Signing material은 Mac 없이도 OpenSSL이나 iOS 인증서 생성기를 통해 생성됩니다. 자세한 내용은 Capacitor와 Capgo Build를 사용하여 Linux에서 iOS 앱 빌드하기, 이는 WSL2에도 동일하게 적용됩니다.

8) 일상적인 변경 사항에는 Native Build를 피하세요

두 앱이 스토어에 출시되면, Capgo Live Updates Gradle이나 Capgo Native Build를 건드리지 않고 WSL2에서 웹 변경 사항을 푸시하세요:

bunx @capgo/cli@latest bundle upload --channel production

흔한 WSL2 문제

adb: device offline 또는 WSL2의 빈 리스트: Windows adb 서버가 실행 중이 아니거나 -a, 버전이 다를 수 있습니다. 서버를 재시작하고 adb version 양쪽 버전을 비교해 보세요.
재부팅 후 호스트 IP 변경: mirrored networking을 사용하지 않으면 발생할 수 있습니다. WSL_HOST export를 ~/.bashrc 에 넣어 다시 계산하거나, mirrored mode로 전환하세요.
Vite가 파일 변경을 감지하지 못함: 프로젝트가 다음 경로에 있음 /mnt/c. Linux 홈 디렉토리로 이동하세요.
Gradle 속도가 매우 느림: 동일한 원인이거나 Gradle 캐시가 /mnt/c. 유지됨 ~/.gradle WSL2 내에.
시간 동기화 오류로 Apple API 인증 실패 build init: 절전 모드 후 WSL2 시간이 어긋남. 다음을 실행하세요: sudo hwclock -s 후 다시 시도하세요.
cap open android 실패함: Studio가 Windows에 있음. Studio에서 폴더를 직접 여세요.

요약

팀원들이 bash 환경을 주로 사용한다면, Capacitor 웹 툴체인을 위한 최적의 환경은 WSL2입니다. 에뮬레이터와 디바이스는 Windows에 두고 adb server로 연결하며, 파일은 Linux 파일 시스템에 저장하고, iOS 컴파일은 Capgo Build에 맡기세요. 이렇게 하면 Windows 노트북에서도 두 앱 스토어 모두에 배포 가능한 Linux 워크플로우를 구축할 수 있습니다.