Le live reload remplace le cycle lent build, sync, run par un simple enregistrement et vérification. Sur un Mac, le Capacitor CLI --live-reload fonctionne généralement sans souci. Sur Windows et Linux, le même flag fonctionne aussi, mais les pare-feu, le réseau de l’émulateur et le routage USB sont à l’origine de la plupart des signalements « ça ne se recharge 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.
- Simple
http://nécessitecleartext: 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 le chemin le plus rapide. Le reste de ce guide utilise la configuration explicite, plus facile à déboguer et compatible avec le serveur de développement de n'importe quel framework.
Option B : configuration explicite
Démarrer le serveur de développement 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 configuration Capacitor réservée au développement. Capacitor lit capacitor.config.ts, activez donc 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
Sous 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 configuration normale et les builds de release sont sûrs.
Émulateur : utilisez 10.0.2.2
Dans l’émulateur Android, 10.0.2.2 c’est votre ordinateur. Cela fonctionne sous Windows et Linux sans modifier le pare-feu, car le trafic ne quitte jamais la machine. Si cela échoue encore, vérifiez que le serveur de dev écoute sur 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 Wi-Fi ni règle de pare-feu :
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é quand l'appareil se reconnecte, 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 et pare-feu
Si l’USB n’est pas une option, utilisez l’IP LAN de votre ordinateur et ouvrez le port.
Trouver l’IP :
# Linux
ip -4 addr show | grep inet
# Windows
ipconfig
Ouvrir le port sur Windows. Depuis un PowerShell en administrateur :
netsh advfirewall firewall add rule name="Vite dev server" dir=in action=allow protocol=TCP localport=5173
Les profils de réseau public de Windows bloquent les connexions entrantes, même avec une règle, dans certaines configs d’entreprise ; passez le Wi-Fi en Privé dans les Paramètres si le téléphone ne se connecte toujours pas.
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 réseau en mode miroir dans .wslconfig ou ajoutez un proxy de port sur Windows. Les détails figurent 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 il faut forcer 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 configuré tente de charger depuis une machine absente, et l'application affiche un écran blanc. Protégez-vous contre cela :
- Utilisez le modèle de variables d'environnement ci-dessus pour que la configuration par défaut n'ait aucun
serverbloc. - Ajoutez un check CI qui échoue si le build
android/app/src/main/assets/capacitor.config.jsoncontient"url". - Si vous utilisez également Live Updates Capgo, sachez qu'une
server.urlconfig é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.