Zum Hauptinhalt springen

Capacitor Live Reload auf Android von Windows und Linux aus

Sofortiges Reload auf einem Android-Emulator oder USB-Handy von einem Windows- oder Linux-Rechner: server.url-Konfiguration, 10.0.2.2, adb reverse, Firewall-Regeln, Cleartext-Traffic und wie du vermeidest, die Dev-Konfiguration mit auszuliefern.

Capacitor Live Reload auf Android von Windows und Linux Capgo Blog-Illustration

Live Reload verwandelt den langsamen Build-, Sync- und Run-Zyklus in Speichern und Schauen. Auf einem Mac funktioniert das Capacitor CLI’s --live-reload Flag meist einfach so. Auf Windows und Linux funktioniert dasselbe Flag ebenfalls, aber Firewalls, Emulator-Netzwerke und USB-Routing verursachen die meisten „Es lädt nicht neu“-Meldungen. Dieser Guide behandelt jeden Fall.

So funktioniert Live Reload in Capacitor

Die Native App lädt normalerweise dist/ aus dem APK heraus. Mit server.url gesetzt, lädt die WebView stattdessen von einer URL, nämlich deinem Vite- oder Framework-Dev-Server. Hot Module Replacement funktioniert dann genau wie in einem Desktop-Browser. Am Native Code ändert sich nichts; nur der Page-Origin wechselt.

Zwei Konsequenzen:

  • Das Gerät benötigt Netzwerkzugriff auf deinen Computer.
  • Einfaches http:// benötigt cleartext: true, da Android Klartext-Verkehr standardmäßig blockiert.

Option A: das CLI-Flag

Die Capacitor CLI kann das für einen einzelnen Lauf einrichten:

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

Ersetze den Host durch die LAN-IP deines Computers. Die CLI schreibt eine temporäre Konfiguration, startet die App und stellt die Konfiguration anschließend wieder her. Falls dein Dev-Server einen anderen Port verwendet, übergebe ihn.

Das ist der schnellste Weg. Der Rest dieses Guides verwendet die explizite Konfiguration, die leichter zu debuggen ist und mit dem Dev-Server jedes Frameworks funktioniert.

Option B: explizite Konfiguration

Starte den Dev-Server, gebunden an alle 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

Then create a dev-only Capacitor config. Capacitor reads capacitor.config.ts, also aktiviere eine Umgebungsvariable:

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;

Führe mit der gesetzten Variable aus:

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

In Windows PowerShell:

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

Ohne die Variable cap sync wird eine normale Konfiguration geschrieben und Release-Builds sind sicher.

Emulator: nutze 10.0.2.2

Im Android-Emulator ist 10.0.2.2 dein Computer. Das funktioniert unter Windows und Linux ohne Firewall-Änderungen, da der Traffic die Maschine nie verlässt. Falls es trotzdem nicht klappt, prüfe, ob der Dev-Server an 0.0.0.0 und nicht nur 127.0.0.1; ein an Loopback gebundener Server ist aus dem virtuellen Netzwerk des Emulators nicht erreichbar.

USB-Handy: adb reverse

Die sauberste Option für ein physisches Gerät, ganz ohne WLAN oder Firewall-Regel:

adb reverse tcp:5173 tcp:5173

Jetzt localhost:5173 auf dem Handy verweist auf deinen Computer. Passe die URL entsprechend an:

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

adb reverse wird beim Reconnect des Geräts gelöscht, also nach dem Ausstecken erneut ausführen. CLI kann das für dich übernehmen: bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173. Linux-User benötigen die udev-Regel aus dem Linux-Setup-Guide bevor adb erkennt das Handy.

WLAN-Handy: LAN-IP plus Firewall

Falls USB keine Option ist, nutze die LAN-IP deines Rechners und öffne den Port.

IP finden:

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

Port unter Windows öffnen. In einer PowerShell mit Admin-Rechten:

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

In manchen Firmennetzwerken blockieren öffentliche Netzwerkprofile unter Windows eingehende Verbindungen trotz Regel; wechsle das WLAN in den Einstellungen auf „Privat“, wenn das Handy sich weiterhin nicht verbinden kann.

Unter Linux mit ufw:

sudo ufw allow 5173/tcp

Unter Fedora mit firewalld:

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

Danach:

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

Beide Geräte müssen sich im selben Subnetz befinden. Gast-WLANs isolieren Clients oft, was sich exakt wie ein Firewall-Problem anfühlt.

WSL2-Besonderheiten

Wenn Vite in WSL2 läuft, stellt der Windows-Host den Port nicht automatisch bereit. Aktiviere „mirrored networking“ in .wslconfig oder richte einen Port-Proxy unter Windows ein. Details findest du im WSL2-Guide.

HMR-Websocket-Probleme

Die Seite lädt, aber Änderungen werden nicht übernommen? Der HMR-Websocket versucht, sich mit dem falschen Host zu verbinden. Gib Vite die öffentliche Adresse an:

// 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 und Next.js bieten äquivalente Optionen; das Symptom ist identisch und die Lösung besteht darin, den Websocket-Host festzulegen.

Debugging mit Chrome DevTools

Öffne chrome://inspect in Chrome oder Edge auf deinem Computer. Die WebView erscheint unter dem Gerät mit der Dev-Server-URL. Du erhältst Konsole, Netzwerk, Quellen und Breakpoints – auf Windows und Linux gleichermaßen. Falls das Gerät nicht erscheint, prüfe adb devices und dass USB-Debugging akzeptiert wurde.

Nie die Dev-Konfiguration ausliefern

Ein Release-Build mit server.url set lädt von einer Maschine, die nicht erreichbar ist, und die App zeigt einen leeren Bildschirm. Dagegen absichern:

  • Nutze das oben gezeigte Umgebungsvariablen-Muster, damit die Standard-Konfiguration keinen server Block enthält.
  • Füge einen CI-Check hinzu, der fehlschlägt, wenn der android/app/src/main/assets/capacitor.config.json enthält "url".
  • Falls du auch Capgo Live Updatesverwendest, beachte, dass eine server.url Konfiguration das Bundle des Updaters überschreibt; halte die beiden Workflows getrennt.

Zusammenfassung

Live Reload auf Android funktioniert unter Windows und Linux, wenn drei Details stimmen: Dev-Server an alle Interfaces binden, die Adresse wählen, die das Gerät tatsächlich erreichen kann (10.0.2.2 für den Emulator, adb reverse for USB, LAN IP with a firewall rule for Wi-Fi), and keep the dev config out of release builds. Once the iteration loop is fast on Android, the shared web layer is already tested before it reaches iOS through Capgo Build.

Live-Updates für Capacitor-Apps

Wenn ein Bug im Web-Layer live ist, liefere den Fix über Capgo aus, statt Tage auf die App-Store-Freigabe zu warten. Nutzer bekommen das Update im Hintergrund, während native Änderungen im normalen Review-Prozess bleiben.

Neues aus unserem Blog

Capgo gibt dir die besten Insights, um eine wirklich professionelle Mobile App zu erstellen.