WSL2는 Windows 개발자에게 진짜 Linux 셸을 제공합니다. 팀의 스크립트, Dockerfile, CI가 모두 bash를 전제로 한다면 이게 중요하죠. Capacitor에서도 잘 작동하는데, 규칙은 하나입니다. 웹 툴체인은 WSL2에 두고, Android 에뮬레이터, USB 장치, Android Studio는 Windows에 두세요. 그런 다음 adb로 둘을 연결하세요.
이 가이드는 그 설정, 사람들이 자주 막히는 네트워크 세부 사항, 그리고 iOS가 어떻게 통합되는지 보여줍니다 Capgo 빌드.
WSL2가 유용한 경우
WSL2를 사용하는 경우:
- 리포지토리에 PowerShell에서 깨지는 bash 스크립트, Makefile 또는 Husky 훅이 있는 경우
- 로컬과 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를 사용하세요. WSL 확장이 있는 VS Code에서 파일을 바로 열 수 있습니다 code ..
이게 중요한 이유: 를 통한 파일 시스템 간 접근은 /mnt/c 에 있는 수천 개의 작은 파일을 처리할 때 느리고 node_modules, Vite가 사용하는 inotify 워처도 Windows 드라이브의 파일을 안정적으로 감지하지 못합니다.
3) Android SDK 위치 결정
두 가지 실행 가능한 레이아웃:
레이아웃 A (권장): Windows에 SDK, WSL2의 Gradle은 Linux SDK 복사본을 가리킵니다. 에뮬레이터와 GUI 도구용으로 Windows에 Android Studio를 설치하고, Gradle용으로 WSL2 안에 별도의 커맨드라인 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
네, 몇백 MB가 중복됩니다. 대신 Gradle이 Linux 속도로 실행되고 /mnt/c.
레이아웃 B: 모든 것을 Windows에 두고, WSL2는 웹 빌드에만 사용. 명령어를 실행했는데 bun run build WSL2에서 cap sync 및 gradlew 동일한 파일에 대해 PowerShell에서 \\wsl$동작은 하지만 속도가 느리고 두 셸이 혼재됩니다. WSL2에 아무것도 설치할 수 없는 경우에만 선택하세요.
이 가이드의 나머지 부분은 Layout A를 전제로 합니다.
4) WSL2와 Windows 간 adb 브리지 설정
에뮬레이터와 USB 연결된 폰은 Windows에 연결되어 있습니다. WSL2의 Gradle 빌드와 cap run android 이 장치에 접근해야 합니다. adb 서버는 Windows에 하나만 두고 WSL2는 클라이언트로 사용하세요.
Windows에서 모든 인터페이스를 경청하도록 adb 서버를 시작합니다. Windows의 SDK에 포함된 adb를 사용하세요:
adb kill-server
adb -a -P 5037 nodaemon server
해당 창을 열어 두세요. WSL 가상 어댑터에 대해 Windows 방화벽에서 포트 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 이상에서는 WSL2가 Windows 네트워크 스택을 공유하도록 mirrored networking을 활성화하세요. 다음을 생성하거나 편집하세요 %USERPROFILE%\.wslconfig:
[wsl2]
networkingMode=mirrored
실행 wsl --shutdown, Ubuntu를 다시 열고 다음을 사용하세요 ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. 이제 재부팅할 때마다 호스트 IP가 변경되지 않으며, live reload도 더 쉬워집니다.
대안: USB 장치를 WSL2로 전달하기
실제 휴대폰에서 adb를 WSL2 내부에서 완전히 사용하려면 usbipd-win을 사용하세요:
winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3
그 다음 WSL2 내부에서 Linux 가이드 의 udev 규칙을 추가하세요. 이는 네트워크 연결로 유지되는 에뮬레이터에는 도움이 되지 않습니다.
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 에뮬레이터나 폰에서 실행됩니다. 에뮬레이터가 dev server에 접근할 수 있어야 합니다.
모든 인터페이스에 바인딩하여 Vite를 시작하세요:
bun run dev -- --host 0.0.0.0
에서 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 config를 변경한 후 실행하고, server 블록은 릴리스 빌드 전에 제거하세요.
7) WSL2에서 Capgo Build로 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/ 프로젝트를 업로드하고 로그를 WSL2 터미널로 스트리밍합니다. 서명 자료는 Mac 없이 OpenSSL 또는 iOS 인증서 생성기. 자세한 내용은 Capacitor와 Capgo Build로 Linux에서 iOS 앱 빌드하기, WSL2에도 그대로 적용됩니다.
8) 일상적인 변경 사항에는 네이티브 빌드 피하기
두 앱이 모두 스토어에 등록되면, Capgo Live Update WSL2에서 Gradle이나 Capgo Build를 건드리지 않고 웹 변경 사항을 push:
bunx @capgo/cli@latest bundle upload --channel production
WSL2에서 흔한 문제들
adb: device offline또는 WSL2에서 빈 목록: Windows adb 서버가 다음으로 실행되지 않음-a, 또는 버전이 다름. 재시작 후 비교adb version양쪽에서.- 재부팅 후 호스트 IP 변경: 미러링 네트워킹이 없으면 예상되는 현상. 다음을
WSL_HOST에 export~/.bashrc하여 재계산되도록 하거나, 미러링 모드로 전환. - Vite가 파일 변경 사항을 감지하지 못함: 프로젝트가 다음 위치에 있음
/mnt/c. Linux 홈으로 이동하세요. - Gradle이 매우 느린 경우: 동일한 원인 또는 Gradle 캐시가 Windows에 있는 경우
/mnt/c.~/.gradle를 WSL2에 유지하세요. - 시계 오차로 인해 Apple API 인증이 실패하는 경우
build init: WSL2 시계는 슬립 후 오차가 발생합니다. 다음을 실행하세요sudo hwclock -s그리고 다시 시도하세요. cap open android실패할 때만 작동합니다: Studio가 Windows에 있습니다. 대신 Studio에서 폴더를 여세요.
요약
팀이 bash 환경에서 작업한다면 WSL2는 Capacitor 웹 툴체인을 위한 좋은 환경입니다. 에뮬레이터와 기기는 Windows에 두고 하나의 adb 서버로 연결하며, 파일은 Linux 파일 시스템에 유지하세요. 그리고 Capgo Build가 iOS 컴파일을 처리하도록 하세요. 그 결과, Windows 노트북에서 Linux 워크플로우를 사용하면서도 두 앱 스토어에 모두 배포할 수 있습니다.