How do I enable live reload in a Capacitor app on Android?

Start your dev server bound to all interfaces, set server.url in capacitor.config.ts to the address the device can reach, add cleartext: true for plain http, run cap sync android and launch the app. The WebView loads from the dev server and reloads on every save.

What address does the Android emulator use to reach my computer?

10.0.2.2. It is the emulator's alias for the host machine's loopback. A physical phone needs your computer's LAN IP, or adb reverse to map a device port to the host over USB.

Why does live reload work on the emulator but not on my phone?

The phone reaches your computer over Wi-Fi, so the dev server port must be open in the Windows Defender or Linux firewall and both devices must be on the same network. adb reverse over USB bypasses the network entirely.

Is it safe to leave server.url in capacitor.config.ts?

No. A release build with server.url set loads your app from a dev machine that is not there. Keep the dev config in a separate file or an environment switch and build releases without it.

Capacitor Live Reload su Android da Windows e Linux

Ottieni il reload istantaneo su un emulatore Android o un dispositivo USB da Windows o Linux: config server.url, 10.0.2.2, adb reverse, regole del firewall, cleartext traffic e come evitare di pubblicare la config di dev.

Il live reload trasforma il lento ciclo build, sync, run in un semplice salva e guarda. Su Mac, il flag Capacitor CLI --live-reload funziona quasi sempre. Anche su Windows e Linux lo stesso flag funziona, ma firewall, networking dell'emulatore e routing USB causano la maggior parte dei report di "non ricarica". Questa guida copre ogni caso.

Come funziona il live reload in Capacitor

Normalmente l'app nativa carica dist/ dall'interno dell'APK. Con server.url impostato, la WebView carica invece da un URL, ovvero il tuo server dev di Vite o del framework. L'hot module replacement funzionerà esattamente come in un browser desktop. Nulla di nativo cambia; cambia solo l'origine della pagina.

Due conseguenze:

Il dispositivo deve avere accesso alla rete del tuo computer.
Semplice http:// necessita cleartext: true, perché Android blocca il traffico cleartext di default.

Opzione A: il flag CLI

La Capacitor CLI può configurare tutto per un'esecuzione:

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

Sostituisci l'host con l'IP LAN del tuo computer. CLI scrive una config temporanea, avvia l'app e ripristina la config in seguito. Se il tuo dev server usa una porta diversa, passala.

Questa è la via più rapida. Il resto della guida utilizza la configurazione esplicita, più facile da debuggare e compatibile con il dev server di qualsiasi framework.

Opzione B: configurazione esplicita

Avvia il dev server su tutte le interfacce:

# 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

Poi crea una configurazione Capacitor solo per lo sviluppo. Capacitor legge capacitor.config.ts, quindi attiva una variabile d'ambiente:

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;

Esegui impostando la variabile:

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

Su Windows PowerShell:

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

Senza la variabile, cap sync scrive una configurazione normale e i release build sono sicuri.

Emulatore: usa 10.0.2.2

All'interno dell'emulatore Android, 10.0.2.2 è il tuo computer. Funziona su Windows e Linux senza modificare il firewall, poiché il traffico non esce mai dalla macchina. Se continua a fallire, conferma che il dev server sia collegato a 0.0.0.0 e non solo 127.0.0.1; un server vincolato al loopback non è raggiungibile dalla rete virtuale dell'emulatore.

Telefono via USB: adb reverse

L'opzione più pulita per un dispositivo fisico, senza bisogno di Wi-Fi o regole del firewall:

adb reverse tcp:5173 tcp:5173

Ora localhost:5173 sul telefono punta al tuo computer. Configura l'URL di conseguenza:

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

adb reverse viene cancellato quando il dispositivo si riconnette, quindi riesegui il comando dopo averlo scollegato. CLI può farlo al posto tuo: bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173Gli utenti Linux hanno bisogno della regola udev da guida alla configurazione Linux prima adb vede il telefono.

Telefono via Wi-Fi: IP LAN e firewall

Se la USB non è un'opzione, usa l'IP LAN del computer e apri la porta.

Trova l'IP:

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

Apri la porta su Windows. Da un PowerShell con privilegi di amministratore:

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

I profili di rete pubblica su Windows bloccano le connessioni in entrata anche con una regola in alcuni setup aziendali; se il telefono non si connette, imposta la rete Wi-Fi su Privata nelle Impostazioni.

Su Linux con ufw:

sudo ufw allow 5173/tcp

Su Fedora con firewalld:

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

Poi:

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

Entrambi i dispositivi devono essere sulla stessa subnet. Le reti Wi-Fi Guest spesso isolano i client, il che sembra esattamente un problema di firewall.

Specifiche per WSL2

Quando Vite gira dentro WSL2, l'host Windows non espone automaticamente la porta. Abilita il mirrored networking in .wslconfig o aggiungi un port proxy su Windows. I dettagli sono nella guida WSL2.

Problemi con il websocket HMR

La pagina si carica ma le modifiche non vengono applicate? Il websocket HMR sta cercando di connettersi all'host sbagliato. Indica a Vite l'indirizzo pubblico:

// 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 e Next.js hanno opzioni equivalenti; il sintomo è lo stesso e la soluzione è fissare l'host del websocket.

Debug con Chrome DevTools

Apri chrome://inspect su Chrome o Edge dal tuo computer. La WebView apparirà sotto il dispositivo con l'URL del dev server. Avrai accesso a console, network, sources e breakpoint, sia su Windows che su Linux. Se il dispositivo non appare, controlla adb devices e che il debugging USB sia autorizzato.

Non pubblicare mai la config di dev

Una release build con server.url si tenta di caricare dati da una macchina non disponibile e l'app mostra una schermata bianca. Per evitarlo:

Usa il pattern delle variabili d'ambiente visto sopra, così la config di default non avrà server blocchi.
Aggiungi un controllo CI che fallisce se il build android/app/src/main/assets/capacitor.config.json contiene "url".
Se utilizzi anche Live Updates di Capgo, tieni presente che una server.url config sovrascrive il bundle dell'updater; mantieni i due workflow separati.

Riassunto

Il Live reload su Android funziona da Windows e Linux se segui tre dettagli: vincola il dev server a tutte le interfacce, scegli l'indirizzo raggiungibile dal dispositivo ("10.0.2.2 per l'emulatore, adb reverse per USB, l'IP LAN con una regola firewall per il Wi-Fi), e tieni la dev config fuori dai release build. Una volta che il ciclo di iterazione è veloce su Android, il web layer condiviso è già testato prima di arrivare su iOS tramite Build Capgo.