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 sur Android depuis Windows et Linux

Obtenez un reload instantané sur un émulateur Android ou un téléphone via USB depuis Windows ou Linux : config server.url, 10.0.2.2, adb reverse, règles de firewall, cleartext traffic, et comment éviter de déployer la config de dev.

Le live reload transforme la boucle lente build, sync, run en un simple save and look. Sur Mac, le flag Capacitor CLI --live-reload fonctionne presque toujours. Sur Windows et Linux, ce même flag fonctionne aussi, mais les firewalls, le réseau de l'émulateur et le routage USB causent la plupart des rapports de type « ça ne reload pas ». Ce guide couvre chaque cas.

Comment fonctionne le live reload dans Capacitor

L'application native se charge normalement dist/ depuis l'intérieur de l'APK. Avec server.url configuré, la WebView se charge depuis une URL à la place : celle de votre serveur de dev Vite ou de votre framework. Le Hot Module Replacement fonctionne alors exactement comme dans un navigateur de bureau. Rien de natif ne change ; seule l'origine de la page change.

Deux conséquences :

L'appareil doit avoir accès à votre ordinateur sur le réseau.
Texte brut http:// nécessite cleartext: true, car Android bloque par défaut le trafic en clair.

Option A : le flag CLI

Le Capacitor CLI peut configurer cela pour une exécution :

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

Remplacez l'hôte par l'IP LAN de votre ordinateur. Le CLI écrit une config temporaire, lance l'app puis restaure la config. Si votre serveur de dev utilise un autre port, indiquez-le.

C'est la méthode la plus rapide. Le reste de ce guide utilise la config explicite, plus facile à débugger et compatible avec le serveur de dev de n'importe quel framework.

Option B : config explicite

Lancez le serveur de dev lié à toutes les interfaces :

# 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

Créez ensuite une config Capacitor dédiée au dev. Capacitor lit capacitor.config.ts, alors activez une variable d'environnement :

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;

Exécutez avec la variable définie :

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

Sur Windows PowerShell :

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

Sans la variable, cap sync écrit une config normale et les builds de release sont sécurisés.

Émulateur : utilisez 10.0.2.2

À l'intérieur de l'émulateur Android, 10.0.2.2 est votre ordinateur. Cela fonctionne sur Windows et Linux sans modifier le firewall, car le trafic ne quitte jamais la machine. Si cela échoue encore, vérifiez que le serveur de dev est bien lié à 0.0.0.0 et pas seulement 127.0.0.1; un serveur lié au loopback n'est pas accessible depuis le réseau virtuel de l'émulateur.

Téléphone USB : adb reverse

L'option la plus propre pour un appareil physique, sans besoin de Wi-Fi ni de règle de firewall :

adb reverse tcp:5173 tcp:5173

Maintenant localhost:5173 sur le téléphone pointe vers votre ordinateur. Configurez l'URL en conséquence :

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

adb reverse est effacé lors de la reconnexion de l'appareil, relancez-le donc après l'avoir débranché. CLI peut le faire pour vous : bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173. Les utilisateurs Linux ont besoin de la règle udev du guide de configuration Linux avant adb voit le téléphone.

Téléphone Wi-Fi : IP LAN plus firewall

Si l'USB n'est pas une option, utilisez l'IP LAN de votre ordinateur et ouvrez le port.

Trouvez l'IP :

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

Ouvrez le port sur Windows. Depuis un PowerShell en mode administrateur :

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

Les profils réseau public sur Windows bloquent les connexions entrantes, même avec une règle, dans certains environnements d'entreprise ; passez le réseau Wi-Fi en mode Privé dans les Paramètres si le téléphone ne parvient toujours pas à se connecter.

Sur Linux avec ufw :

sudo ufw allow 5173/tcp

Sur Fedora avec firewalld :

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

Ensuite :

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

Les deux appareils doivent être sur le même sous-réseau. Les réseaux Wi-Fi invités isolent souvent les clients, ce qui ressemble exactement à un problème de pare-feu.

Spécificités de WSL2

Lorsque Vite s'exécute dans WSL2, l'hôte Windows n'expose pas automatiquement le port. Activez le mode mirrored networking dans .wslconfig ou ajoutez un proxy de port sur Windows. Les détails se trouvent dans le guide WSL2.

Problèmes de websocket HMR

La page se charge mais les changements ne s'appliquent pas ? Le websocket HMR tente de se connecter au mauvais hôte. Indiquez l'adresse publique à Vite :

// 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 et Next.js ont des options équivalentes ; le symptôme est identique et la solution consiste à fixer l'hôte du websocket.

Débogage avec Chrome DevTools

Ouvrez chrome://inspect dans Chrome ou Edge sur votre ordinateur. La WebView apparaît sous l'appareil avec l'URL du serveur de dev. Vous avez accès à la console, au réseau, aux sources et aux points d'arrêt, aussi bien sur Windows que sur Linux. Si l'appareil n'apparaît pas, vérifiez adb devices et que le débogage USB est accepté.

Ne déployez jamais la config de dev

Un build de release avec server.url définir des chargements depuis une machine inexistante, ce qui affiche un écran blanc dans l'app. Évitez cela :

Utilisez le modèle de variables d'environnement ci-dessus pour que la configuration par défaut n'ait aucun server bloc.
Ajoutez un check CI qui échoue si le build android/app/src/main/assets/capacitor.config.json contient "url".
Si vous utilisez également Capgo Live Updates, sachez qu'une server.url config écrase le bundle de l'updater ; gardez les deux workflows séparés.

Résumé

Le live reload sur Android fonctionne depuis Windows et Linux avec trois détails à bien régler : liez le serveur de dev à toutes les interfaces, choisissez l'adresse que l'appareil peut réellement atteindre (10.0.2.2 pour l'émulateur, adb reverse pour l'USB, l'IP LAN avec une règle de firewall pour le Wi-Fi), et gardez la config de dev hors des builds de release. Une fois que la boucle d'itération est rapide sur Android, la couche web partagée est déjà testée avant d'arriver sur iOS via Build Capgo.