Aller au contenu principal

Capacitor Live Reload sur Android depuis Windows et Linux

Obtenez un rechargement instantané sur un émulateur Android ou un téléphone branché en USB depuis une machine Windows ou Linux : configuration server.url, 10.0.2.2, adb reverse, règles de pare-feu, trafic en clair et comment éviter de livrer la config de dev.

Illustration du blog : Capacitor live reload sur Android depuis Windows et Linux Capgo

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é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 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 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 Live Updates Capgo, 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.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.