Zum Hauptinhalt springen

Capacitor Entwicklung unter Linux: Der komplette Setup-Guide

Richten Sie einen vollständigen Capacitor-Workflow unter Ubuntu, Fedora oder Arch ein: Node oder Bun, JDK, Android SDK, Emulator mit KVM, USB-Geräte mit udev-Regeln und iOS-Builds ohne Mac mit Capgo Build.

Capacitor Entwicklung auf Linux: Setup-Anleitung Capgo Blog-Illustration

Linux ist eine hervorragende Plattform für Capacitor-Arbeit. Die Web-Ebene besteht nur aus Node-Tooling, das Android-Tooling läuft nativ, und der Linux-Emulator mit KVM ist oft schneller als derselbe Emulator unter Windows. Die einzige Lücke ist iOS: Xcode existiert nur auf macOS, daher benötigen Sie für diesen Teil einen Cloud-Build-Dienst.

Diese Anleitung führt durch ein vollständiges Linux-Setup, getestet auf Ubuntu 24.04, Fedora 42 und Arch. Sie endet mit einem iOS-Build von Linux aus, wobei Capgo Build, damit du beide Stores bespielen kannst, ohne einen Mac zu besitzen.

Was auf Linux funktioniert und was nicht

Aufgabe Linux
Webentwicklung, Vite, Framework-Tooling Ja
cap add android, cap sync, Gradle-Builds Ja
Android-Emulator Ja, mit KVM
Physisches Android-Gerät via USB Ja, mit udev-Regeln
Remote-Debugging mit Chrome DevTools Ja
cap add ios, cap sync ios (generieren und kopieren) Ja, mit dem Hinweis, dass CocoaPods übersprungen wird
iOS kompilieren, signieren, archivieren Nein, benötigt macOS. Nutze Capgo Build
iOS-Simulator Nein
Safari Web Inspector für iOS WebView Nein

Alles in den „Nein“-Zeilen wandert in die Cloud oder auf ein echtes iPhone mit TestFlight. Das behandeln wir am Ende.

1) Node oder Bun installieren

CLI von Capacitor benötigt Node 20 oder neuer. Bun dient als Runtime und Package Manager und ist bei Installationen schneller.

# Bun (recommended)
curl -fsSL https://bun.sh/install | bash

# Or Node via your package manager
# Ubuntu / Debian
sudo apt install -y nodejs npm
# Fedora
sudo dnf install -y nodejs
# Arch
sudo pacman -S nodejs npm

Versionen prüfen:

bun --version
node --version

2) JDK installieren

Capacitor 7 und 8 benötigen JDK 21. Distributionspakete sind okay.

# Ubuntu / Debian
sudo apt install -y openjdk-21-jdk

# Fedora
sudo dnf install -y java-21-openjdk-devel

# Arch
sudo pacman -S jdk21-openjdk

Setzen Sie JAVA_HOME in einem ~/.bashrc oder ~/.zshrc. Der Pfad hängt von der Distribution ab:

# Ubuntu / Debian
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# Fedora
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
# Arch
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk

Falls mehrere JDKs installiert sind, wählt Gradle das, JAVA_HOME auf das gezeigt wird. Eine falsche Version zeigt sich als Unsupported class file major version während cap run android.

3) Installiere das Android SDK

Du hast zwei Optionen. Android Studio bietet dir GUI-Tools. Die Command-Line-Tools allein sind schlanker und reichen zum Build aus.

Option A: Android Studio

Lade das Linux-Tarball von der Android-Studio-Website herunter und entpacke es:

sudo tar -xzf android-studio-*.tar.gz -C /opt
/opt/android-studio/bin/studio.sh

Beim ersten Start installiert der Setup-Wizard das SDK in ~/Android/Sdk.

Capacitors cap open android muss wissen, wo Studio liegt:

export CAPACITOR_ANDROID_STUDIO_PATH=/opt/android-studio/bin/studio.sh

Option B: Nur Command-Line-Tools

mkdir -p ~/Android/Sdk/cmdline-tools
cd ~/Android/Sdk/cmdline-tools
# Download "Command line tools only" for Linux from the Android developer site, then:
unzip commandlinetools-linux-*.zip
mv cmdline-tools latest

Füge das SDK deinem Shell-Profil hinzu:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

Installiere, was Capacitor benötigt, und akzeptiere die Lizenzen:

sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "emulator"
sdkmanager --licenses

Passe die Plattform-Version an die compileSdkVersion in deinem generierten android/variables.gradle. Capacitor 8 uses 36; Capacitor 7 uses 35.

4) KVM für den Emulator aktivieren

Ohne KVM ist der Emulator unbrauchbar. Prüfe, ob deine CPU Virtualisierung unterstützt:

egrep -c '(vmx|svm)' /proc/cpuinfo

Ein Wert über 0 bedeutet, dass es unterstützt wird. Installiere KVM und gewähre deinem Benutzer Zugriff:

# Ubuntu / Debian
sudo apt install -y qemu-kvm
# Fedora
sudo dnf install -y qemu-kvm
# Arch
sudo pacman -S qemu-base

sudo usermod -aG kvm $USER

Melde dich ab und wieder an. Erstelle und starte ein Gerät:

sdkmanager "system-images;android-36;google_apis;x86_64"
avdmanager create avd -n pixel8 -k "system-images;android-36;google_apis;x86_64" -d pixel_8
emulator -avd pixel8

Falls der Emulator über /dev/kvm Berechtigungen klagt, wurde deine Gruppenänderung noch nicht angewendet. Starte neu.

5) USB-Zugriff für physische Geräte

Linux erlaubt regulären Benutzern standardmäßig keine Kommunikation mit USB-Geräten. Füge eine udev-Regel hinzu:

sudo tee /etc/udev/rules.d/51-android.rules > /dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="2a70", MODE="0666", GROUP="plugdev"
EOF
sudo udevadm control --reload-rules
sudo usermod -aG plugdev $USER

Die oben genannten Vendor-IDs decken Google, Samsung und OnePlus ab. Finde deine mit lsusb falls dein Telefon nicht aufgelistet ist. Aktiviere USB-Debugging am Telefon, schließe es an, akzeptiere den Fingerabdruck-Hinweis, dann:

adb devices

6) Das Capacitor-Projekt erstellen

bun create vite@latest my-app
cd my-app
bun install
bun add @capacitor/core @capacitor/android @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add android
bunx cap add ios

cap add ios auf Linux gibt eine Warnung aus, dass CocoaPods nicht verfügbar ist. Das ist erwartet. Der ios/ Ordner wird trotzdem erstellt und ist das, was Capgo Build später kompiliert.

Auf dem Emulator oder Gerät ausführen:

bunx cap run android

WebView in Chrome debuggen unter chrome://inspect.

7) Release-Builds auf Linux

Android-Release-Builds laufen vollständig lokal. Erstelle ein Keystore mit dem JDK- keytool:

keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release

Dann bauen:

cd android
./gradlew bundleRelease

Die AAB landet in android/app/build/outputs/bundle/release/. Wenn du Signing-Keys nicht auf Laptops aufbewahren möchtest, Capgo Build für Android speichert das Keystore einmal ab und baut in der Cloud mit demselben CLI, den du für iOS nutzt.

8) iOS von Linux mit Capgo Build

Das ist der Schritt, den Linux allein nicht schafft. Der Workflow:

  1. Erstelle deine Web-Assets und synchronisiere sie in ios/.
  2. Speichere deine iOS-Signing-Credentials einmalig.
  3. Fordere einen Cloud Build an. Capgo kompiliert, signiert und kann zu TestFlight hochladen.
bun run build
bunx cap sync ios

bunx @capgo/cli@latest login
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

build init führt dich durch die Credentials. Unter Linux erstellst du den App Store Connect API Key manuell im Apple-Portal; der iOS-Build-Anleitung zeigt jeden Klick. Für das Distribution Certificate brauchst du Keychain Access nie: Generiere den CSR und .p12 with OpenSSL as described in iOS-Zertifikate und Provisioning Profiles erklärt, oder nutze den iOS-Zertifikatsgenerator.

Logs streamen live in dein Terminal. Der komplette Linux-zu-TestFlight-Flow ist ausführlich beschrieben in Eine iOS-App unter Linux bauen mit Capacitor und Capgo Build.

9) Native Rebuilds mit Live Updates überspringen

Sobald die Native Shells in den Stores sind, bestehen die meisten täglichen Änderungen aus JavaScript, HTML und CSS. Die lassen sich in Sekunden von Linux aus deployen mit Capgo Live Updates:

bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production

Nutze Native Builds nur für Plugin-Änderungen, Berechtigungsänderungen und Capacitor-Upgrades.

Häufige Linux-Probleme

  • SDK location not found: ANDROID_HOME ist in der Shell, die Gradle ausführt, nicht exportiert. Füge es deinem Profil hinzu und öffne ein neues Terminal, oder erstelle android/local.properties mit sdk.dir=/home/you/Android/Sdk.
  • Unsupported class file major version: falsches JDK. Verweise JAVA_HOME auf JDK 21.
  • Emulator: schwarzer Bildschirm oder sehr langsam: KVM ist nicht aktiv. Prüfe ls -l /dev/kvm und Ihre Gruppenmitgliedschaft.
  • adb devices zeigt no permissions: udev-Regel fehlt oder wurde nicht neu geladen. Gerät nach dem Neuladen trennen und wieder verbinden.
  • Gradle-Daemon läuft aus dem Speicher: hinzufügen org.gradle.jvmargs=-Xmx4g zu android/gradle.properties.
  • Wayland- und Android-Studio-Fehler: Studio starten mit _JAVA_AWT_WM_NONREPARENTING=1 falls Fenster leer bleiben.

Zusammenfassung

Linux verarbeitet den kompletten Capacitor-Workflow für Android und die Web-Ebene nativ – oft schneller als andere Desktop-Systeme. Für iOS das Projekt lokal generieren, Assets synchronisieren und Capgo Build den macOS-Teil übernehmen lassen. Kombiniert mit Live Updates denkst du nur dann an Xcode, wenn Apple die Mindestversion von SDK ändert.

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.