본문 바로가기

Windows 및 Linux에서 Android Capacitor Live Reload 사용하기

Windows 또는 Linux 머신에서 Android 에뮬레이터나 USB 연결 휴대폰으로 즉시 리로드하기: server.url 설정, 10.0.2.2, adb reverse, 방화벽 규칙, cleartext traffic, 개발용 설정을 배포하지 않는 방법까지 다룹니다.

Windows 및 Linux에서 Android용 Capacitor live reload 사용하기 Capgo 블로그 일러스트

Live reload를 사용하면 느린 build, sync, run 루프가 '저장 후 바로 확인'으로 바뀝니다. Mac에서는 Capacitor CLI의 --live-reload flag가 대부분 잘 작동합니다. Windows와 Linux에서도 동일한 flag가 작동하지만, 방화벽, 에뮬레이터 네트워킹, USB 라우팅 문제로 인해 “리로드가 안 돼요”라는 보고가 가장 많이 발생합니다. 이 가이드에서 각 케이스를 다룹니다.

Capacitor에서 live reload가 작동하는 방식

일반적으로 네이티브 앱은 dist/ APK 내부에서 로드됩니다. 하지만 server.url 설정하면 WebView가 APK 대신 Vite나 프레임워크 개발 서버 URL에서 로드됩니다. 덕분에 데스크톱 브라우저와 동일하게 HMR(Hot Module Replacement)이 작동합니다. 네이티브 코드는 변경되지 않고 페이지 오리진만 바뀝니다.

두 가지 주의사항이 있습니다:

  • 기기가 컴퓨터의 네트워크에 접속할 수 있어야 합니다.
  • 또한 http:// 설정이 cleartext: true필요합니다. Android는 기본적으로 cleartext 트래픽을 차단하기 때문입니다.

옵션 A: CLI 플래그

Capacitor CLI를 사용하면 한 번의 실행으로 다음과 같이 설정할 수 있습니다:

bun run dev -- --host 0.0.0.0 &
bunx cap run android --live-reload --host 192.168.1.20 --port 5173

호스트를 컴퓨터의 LAN IP로 변경하세요. CLI가 임시 설정을 작성하여 앱을 실행한 뒤, 다시 원래 설정으로 복구합니다. 개발 서버의 포트가 다르다면 해당 포트를 전달하세요.

가장 빠른 방법입니다. 이 가이드의 나머지 부분은 디버깅이 더 쉽고 모든 프레임워크의 dev server에서 작동하는 명시적 설정을 사용합니다.

옵션 B: 명시적 설정

모든 인터페이스에 바인딩하여 dev server를 시작하세요:

# Vite
bun run dev -- --host 0.0.0.0
# Angular
bunx ng serve --host 0.0.0.0
# Next.js
bun run dev -- -H 0.0.0.0

그런 다음 개발 전용 Capacitor 설정을 만드세요. Capacitor은 읽으므로 capacitor.config.ts, 환경 변수를 켜세요:

import type { CapacitorConfig } from '@capacitor/cli';

const liveReloadUrl = process.env.CAP_LIVE_RELOAD_URL;

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  ...(liveReloadUrl
    ? { server: { url: liveReloadUrl, cleartext: true } }
    : {}),
};

export default config;

변수를 설정한 상태로 실행하세요:

CAP_LIVE_RELOAD_URL=http://10.0.2.2:5173 bunx cap sync android
bunx cap run android

Windows PowerShell에서는:

$env:CAP_LIVE_RELOAD_URL="http://10.0.2.2:5173"; bunx cap sync android
bunx cap run android

변수가 없으면, cap sync 일반 설정을 작성하므로 릴리스 빌드는 안전합니다.

에뮬레이터: 10.0.2.2 사용

Android 에뮬레이터 내부에서, 10.0.2.2 사용자의 컴퓨터입니다. 트래픽이 머신 외부로 나가지 않으므로 Windows와 Linux 모두 방화벽 변경 없이 작동합니다. 여전히 실패한다면 dev server가 다음 주소에 바인딩되어 있는지 확인하세요: 0.0.0.0 뿐만 아니라 127.0.0.1; 루프백에 바인딩된 서버는 에뮬레이터의 가상 네트워크에서는 접근할 수 없습니다.

USB 연결 기기: adb reverse

실제 기기에서 가장 깔끔한 방법이며, Wi-Fi나 방화벽 규칙도 필요 없습니다:

adb reverse tcp:5173 tcp:5173

현재 localhost:5173 휴대폰의 URL이 컴퓨터를 가리키도록 합니다. URL을 그에 맞게 설정하세요:

CAP_LIVE_RELOAD_URL=http://localhost:5173 bunx cap sync android

adb reverse 기기가 다시 연결될 때 초기화되므로, 케이블을 뽑은 후 다시 실행하세요. CLI가 대신 처리해 줄 수 있습니다: bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173. Linux 사용자는 다음 문서의 udev 규칙이 필요합니다: Linux 설정 가이드 첫 번째 제출이 승인되기 adb 휴대폰을 인식합니다.

Wi-Fi 연결 기기: LAN IP 및 방화벽

USB 연결이 어렵다면 컴퓨터의 LAN IP를 사용하고 포트를 개방하세요.

IP 확인 방법:

# Linux
ip -4 addr show | grep inet
# Windows
ipconfig

Windows에서 포트 개방하기. 관리자 권한의 PowerShell에서 다음을 실행하세요:

netsh advfirewall firewall add rule name="Vite dev server" dir=in action=allow protocol=TCP localport=5173

Windows의 공용 네트워크 프로필은 일부 기업 환경에서 규칙을 설정해도 인바운드 연결을 차단할 수 있습니다. 연결이 안 된다면 설정에서 Wi-Fi 네트워크를 '개인(Private)'으로 변경하세요.

ufw를 사용하는 Linux의 경우:

sudo ufw allow 5173/tcp

firewalld를 사용하는 Fedora의 경우:

sudo firewall-cmd --add-port=5173/tcp

그 다음:

CAP_LIVE_RELOAD_URL=http://192.168.1.20:5173 bunx cap sync android
bunx cap run android

두 기기는 반드시 동일한 서브넷에 있어야 합니다. 게스트 Wi-Fi 네트워크는 클라이언트를 격리하는 경우가 많으며, 이는 방화벽 문제와 매우 유사하게 나타납니다.

WSL2 특이사항

WSL2에서 Vite를 실행할 때, Windows 호스트가 포트를 자동으로 노출하지 않을 수 있습니다. 다음에서 mirrored networking을 활성화하거나 .wslconfig Windows에 포트 프록시를 추가하세요. 자세한 내용은 WSL2 가이드.

HMR websocket 문제

페이지는 로드되지만 변경 사항이 반영되지 않나요? HMR websocket이 잘못된 호스트에 연결을 시도하고 있습니다. Vite에 다음 public 주소를 설정하세요:

// vite.config.ts
export default defineConfig({
  server: {
    host: '0.0.0.0',
    hmr: {
      host: '192.168.1.20', // or 10.0.2.2 for the emulator
      port: 5173,
    },
  },
});

Angular와 Next.js도 동일한 옵션을 제공합니다. 증상은 같으며, websocket 호스트를 고정하여 해결할 수 있습니다.

Chrome DevTools로 디버깅하기

열기 chrome://inspect 컴퓨터의 Chrome 또는 Edge에서 진행하세요. WebView가 dev server URL과 함께 디바이스 아래에 표시됩니다. Windows와 Linux 모두에서 console, network, sources 및 breakpoint를 사용할 수 있습니다. 디바이스가 보이지 않는다면 다음을 확인하세요: adb devices 및 USB debugging이 허용되었는지 확인하세요.

dev config를 배포하지 마세요

다음 기능을 포함한 release build server.url 존재하지 않는 머신에서 로드를 설정하면 앱에 빈 화면이 나타납니다. 이를 방지하려면:

  • 위의 환경 변수 패턴을 사용하면 기본 설정에 server 블록이 없도록 하세요.
  • 빌드된 결과물에 android/app/src/main/assets/capacitor.config.json contains "url".
  • 또한 사용한다면 Capgo Live Updates, 유의하세요: 설정이 server.url updater의 bundle을 덮어쓰므로 두 워크플로우를 분리하세요.

요약

Android의 Live reload는 Windows와 Linux에서 작동합니다. 세 가지만 제대로 하면 됩니다: dev server를 모든 인터페이스에 바인딩하고, 기기가 실제로 접속할 수 있는 주소를 선택하세요 (10.0.2.2 에뮬레이터의 경우, adb reverse for USB, LAN IP with a firewall rule for Wi-Fi), and keep the dev config out of release builds. Once the iteration loop is fast on Android, the shared web layer is already tested before it reaches iOS through Capgo 빌드.

Capacitor 앱용 Live updates

웹 레이어 버그가 라이브 상태라면, 앱 스토어 승인을 며칠씩 기다리지 말고 Capgo를 통해 수정 사항을 배포하세요. 네이티브 변경 사항은 정상 리뷰 절차를 그대로 따르는 반면, 사용자는 백그라운드에서 업데이트를 받습니다.

블로그 최신 글

Capgo는 정말 프로페셔널한 모바일 앱을 만드는 데 필요한 최고의 인사이트를 제공합니다.