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나 프레임워크의 dev server URL에서 로드됩니다. 그러면 HMR(Hot module replacement)이 데스크톱 브라우저와 동일하게 작동합니다. 네이티브 코드는 변경되지 않고 페이지 origin만 바뀝니다.
두 가지 결과가 따릅니다:
- 기기가 컴퓨터의 네트워크에 접속할 수 있어야 합니다.
- 또한
http://필요합니다.cleartext: trueAndroid는 기본적으로 cleartext traffic을 차단하기 때문입니다.
옵션 A: CLI 플래그
Capacitor CLI를 사용하면 한 번의 실행으로 이를 설정할 수 있습니다:
bun run dev -- --host 0.0.0.0 &
bunx cap run android --live-reload --host 192.168.1.20 --port 5173host를 컴퓨터의 LAN IP로 교체하세요. CLI가 임시 설정을 작성하고 앱을 실행한 뒤 설정을 복구합니다. dev server가 다른 포트를 사용한다면 해당 포트도 함께 전달하세요.
가장 빠른 방법입니다. 이 가이드의 나머지 부분은 디버깅이 더 쉽고 어떤 프레임워크의 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 androidWindows 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을 다음과 같이 맞추세요:
CAP_LIVE_RELOAD_URL=http://localhost:5173 bunx cap sync androidadb 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
ipconfigWindows에서 포트 개방하기. 관리자 권한의 PowerShell에서:
netsh advfirewall firewall add rule name="Vite dev server" dir=in action=allow protocol=TCP localport=5173Windows의 공용 네트워크 프로필은 일부 기업 환경에서 규칙을 설정해도 인바운드 연결을 차단할 수 있습니다. 연결이 안 된다면 설정에서 Wi-Fi 네트워크를 '개인'으로 변경하세요.
ufw를 사용하는 Linux의 경우:
sudo ufw allow 5173/tcpfirewalld를 사용하는 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 관련 주의사항
Vite가 WSL2 내부에서 실행될 때, 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 디버깅이 허용되었는지 확인하세요.
개발용 설정을 배포하지 마세요
A release build with server.url 설정된 주소가 존재하지 않는 머신을 가리키면 앱에 빈 화면이 나타납니다. 이를 방지하려면:
- 위에서 설명한 환경 변수 패턴을 사용하여 기본 설정에 포함되지 않도록 하세요.
server차단 블록. - 빌드된 결과물에 오류가 있을 경우 실패하는
android/app/src/main/assets/capacitor.config.json포함된"url". - 또한 다음을 사용한다면 Capgo Live Updates주의해야 할 점은
server.url설정이 updater의 bundle을 덮어쓴다는 것입니다. 두 워크플로우를 분리해서 관리하세요.
요약
Android에서 Windows 및 Linux를 통한 Live reload를 제대로 사용하려면 세 가지를 기억하세요. 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 빌드.
