Capacitor Live Reload auf Android von Windows und Linux aus

Live Reload verwandelt den langsamen Build-, Sync- und Run-Zyklus in ein schnelles „Speichern und Ansehen“. Auf einem Mac ist das Capacitor CLI’s --live-reload Flag meistens einfach so. Auf Windows und Linux funktioniert das gleiche Flag ebenfalls, aber Firewalls, Emulator-Networking und USB-Routing verursachen die meisten „Reload geht nicht“-Probleme. Dieser Guide deckt alle Fälle ab.

So funktioniert Live Reload in Capacitor

Die native App lädt normalerweise dist/ aus der APK heraus. Mit server.url lädt die WebView stattdessen von einer URL, nämlich deinem Vite- oder Framework-Dev-Server. Hot Module Replacement funktioniert dann exakt wie in einem Desktop-Browser. Nichts am nativen Teil ändert sich; nur der Page Origin.

Zwei Konsequenzen:

• Das Gerät benötigt Netzwerkzugriff auf deinen Rechner.
• Einfach http:// benötigt cleartext: true, da Android unverschlüsselten Traffic standardmäßig blockiert.

Option A: Das CLI Flag

Mit dem Capacitor CLI lässt sich das für einen Durchlauf 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 Rechners. CLI schreibt eine temporäre Config, startet die App und stellt die Config danach wieder her. Falls dein Dev-Server einen anderen Port nutzt, gib ihn mit an.

Das ist der schnellste Weg. Der Rest dieser Anleitung nutzt die explizite Config, die einfacher zu debuggen ist und mit dem Dev Server jedes Frameworks funktioniert.

Option B: explizite Config

Starte den Dev Server auf allen 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

Erstelle dann eine Capacitor Config nur für die Entwicklung. Capacitor liest 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;

Ausführen mit gesetzter Variable:

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

Unter 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 schreibt eine normale Config und Release Builds sind sicher.

Emulator: nutze 10.0.2.2

Innerhalb des Android Emulators 10.0.2.2 ist dein Computer. Das funktioniert unter Windows und Linux ohne Firewall-Änderungen, da der Traffic die Maschine nie verlässt. Falls es trotzdem fehlschlägt, 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, eine falsche Host-Adresse zu erreichen. 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 haben ähnliche Optionen; das Problem 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 Rechner. Die WebView wird unter dem Gerät mit der Dev-Server-URL angezeigt. Du hast Zugriff auf Console, Network, Sources und Breakpoints, sowohl unter Windows als auch unter Linux. Falls das Gerät nicht erscheint, prüfe adb devices und ob das USB-Debugging akzeptiert wurde.

Nutze niemals die Dev-Config im Release

Ein Release-Build mit server.url lädt von einer nicht vorhandenen Maschine und die App zeigt nur einen leeren Bildschirm. So verhinderst du das:

• Nutze das oben beschriebene Environment-Variable-Pattern, damit die Standard-Config keine server block.
• Add a CI check that fails if the built android/app/src/main/assets/capacitor.config.json enthält "url".
• Wenn du auch Capgo Live Updatesnutzt, beachte bitte, dass eine server.url Config das Bundle des Updaters überschreibt; halte die beiden Workflows getrennt.

Zusammenfassung

Live Reload auf Android funktioniert unter Windows und Linux mit drei Details richtig: Binde den Dev-Server an alle Interfaces, wähle die Adresse, die das Gerät tatsächlich erreichen kann (10.0.2.2 für den Emulator, adb reverse für USB die LAN-IP mit einer Firewall-Regel für Wi-Fi), und halte die Dev-Config aus Release-Builds fern. Sobald der Iterationszyklus auf Android schnell ist, ist der gemeinsame Web-Layer bereits getestet, bevor er über Capgo Build.