Salta al contenuto principale

Capacitor Live Reload su Android da Windows e Linux

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

Capacitor live reload su Android da Windows e Linux Capgo illustrazione del blog

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 delle segnalazioni “non fa il reload”. Questa guida copre ogni caso.

Come funziona il live reload in Capacitor

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

Due conseguenze:

  • Il dispositivo deve avere accesso di rete al tuo computer.
  • Un semplice http:// richiede cleartext: true, perché Android blocca il traffico cleartext di default.

Opzione A: il flag CLI

Il Capacitor CLI può configurarlo per una sola 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. Il CLI scrive una configurazione temporanea, avvia l'app e ripristina la configurazione in seguito. Se il tuo server di sviluppo usa una porta diversa, passala.

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

Opzione B: configurazione esplicita

Avvia il dev server in ascolto 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 config 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 con la variabile impostata:

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 le build di release sono sicure.

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, perché il traffico non esce mai dalla macchina. Se continua a fallire, verifica che il dev server sia in ascolto su 0.0.0.0 e non solo 127.0.0.1; un server legato 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 né di regole firewall:

adb reverse tcp:5173 tcp:5173

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

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

adb reverse viene cancellato quando il dispositivo si ricollega, quindi rilancialo dopo lo scollegamento. CLI può farlo per te: bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173. Gli utenti Linux hanno bisogno della regola udev dal guida alla configurazione Linux prima adb vede il telefono.

Telefono via Wi-Fi: IP LAN e firewall

Se 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 elevati:

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 ingresso anche con una regola in alcune configurazioni aziendali; passa la rete Wi-Fi a Privata nelle Impostazioni se il telefono non riesce ancora a connettersi.

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 nella 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 in WSL2, l'host Windows non espone automaticamente la porta. Abilita il mirrored networking in .wslconfig o aggiungi un port proxy su Windows. Trovi i dettagli nella guida WSL2.

Problemi 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 in Chrome o Edge sul tuo computer. La WebView appare 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 accettato.

Non rilasciare mai la config di dev

Una release build con server.url set carica da una macchina che non esiste e l'app mostra uno schermo vuoto. Prevedi questo caso:

  • Usa il pattern di variabile d'ambiente sopra in modo che la configurazione predefinita non server block.
  • Aggiungi un controllo CI che fallisce se il android/app/src/main/assets/capacitor.config.json contiene "url".
  • Se usi 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 azzecchi tre dettagli: vincola il dev server a tutte le interfacce, scegli l'indirizzo a cui il dispositivo può effettivamente accedere (10.0.2.2 per l'emulatore, adb reverse per USB, IP della LAN con una regola del firewall per il Wi-Fi), e tieni la configurazione di sviluppo fuori dai build di release. Quando il ciclo di iterazione è veloce su Android, il layer web condiviso è già testato prima di arrivare su iOS tramite Build Capgo.

Live updates per le app Capacitor

Quando un bug nel web-layer è live, rilascia la fix tramite Capgo invece di aspettare giorni l'approvazione degli store. Gli utenti ricevono l'update in background, mentre le modifiche native restano nel normale processo di review.

Ultimi articoli dal blog

Capgo ti offre gli insight migliori che ti servono per creare un'app mobile davvero professionale.