Mit Capacitor 8 Ihre Nuxt App in iOS- & Android-Anwendungen umwandeln

Einführung

Haben Sie bereits eine Nuxt-Webanwendung? In diesem Leitfaden erfahren Sie, wie Sie sie in native iOS- und Android-Mobilanwendungen umwandeln können, indem Sie Capacitor 8 — die neueste Version mit verbesserten Leistungen und neuen Funktionen.

Capacitor umhüllt Ihre Web-App in einem nativen Container, der Ihnen Zugriff auf Geräte-APIs wie Kamera, Dateisystem und Benachrichtigungen gibt, während Ihre bestehende Vue-Codebasis erhalten bleibt. Im Gegensatz zu Flutter oder React Native müssen Sie nichts umschreiben – Ihre Nuxt code läuft wie gewohnt.

Was Sie lernen werden:

• Konfigurieren Sie Ihre bestehende Nuxt-Anwendung für statische Generierung
• Fügen Sie Capacitor 8 mit wesentlichen nativen Plugins hinzu
• Erstellen und testen Sie auf iOS- und Android-Emulatoren
• Aktivieren Sie Live-Reload für eine schnellere Entwicklung
• Beheben Sie häufige iOS-Ansichtsprobleme (Viewport, sichere Fläche, horizontale Überlauf)
• Fügen Sie natürliche Anzeige mit Capgo Native Navigation und Transitions hinzu

Sind Sie neu bei einem Projekt und möchten von vorne beginnen? Überprüfen Sie unsere Anleitung zu Ein Nuxt-Mobil-App von Grund auf aufbauen.

Vorteile der Verwendung von Nuxt und Capacitor

• Code Reusability: Ihre Vue-Komponenten und Logik teilen Sie zwischen Web- und Mobilanwendungen.
• Leistung: Nuxt’s statische Generierung erstellt optimierte Bundle perfekt für Mobilgeräte.
• Eigene Funktionen: Zugriff auf Gerätefeatures wie Kamera, Geolocation und Dateisystem über Capacitor-Plugins.
• Einfache Entwicklung: Verwenden Sie bekannte Vue/Nuxt-Muster ohne native Entwicklung lernen zu müssen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie haben:

• Node.js 18+ installiert
• Ein bestehendes Nuxt 4 Anwendung
• Xcode (nur für iOS-Entwicklung unter macOS)
• Android Studio (nur für Android-Entwicklung)

Ihre Nuxt-App für Mobilgeräte konfigurieren

Der erste Schritt besteht darin, Ihre Nuxt-App für die statische Generierung zu konfigurieren. Capacitor benötigt statische HTML/JS/CSS-Dateien, um diese in die native App zu packen.

Stellen Sie sicher, dass Ihr package.json den generate-Skript enthält:

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Wichtig: Wenn Sie serverseitige Funktionen (z.B. API Routen, Server-Middleware usw.) verwenden, müssen Sie diese um clientseitige Alternativen oder externe APIs umstellen.

Testen Sie die statische Erzeugung, indem Sie Folgendes ausführen:

bun run generate

Sie sollten ein Verzeichnis mit Ihren statischen Dateien sehen. Dies ist, was __CAPGO_KEEP_0__ in Ihre native App einbündeln wird. .output/public Hinzufügen von Capacitor 8 zu Ihrem Projekt

Adding Capacitor 8 to Your Project

Installieren Sie __CAPGO_KEEP_0__-Core und __CAPGO_KEEP_1__:

1. Install Capacitor core and CLI:

bun add @capacitor/core
bun add -D @capacitor/cli

2. Install common Capacitor plugins you’ll likely need:

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

@__CAPGO_KEEP_0__/app

• @capacitor/app@__CAPGO_KEEP_0__/keyboard
• @capacitor/keyboard@__CAPGO_KEEP_0__/keyboard
• @capacitor/Splashbildschirm: Die native Splashschirmoberfläche verwalten
• @capacitor/Statusleiste: Die Geräte-Statusleiste anpassen
• @capacitor/Einstellungen: Schlüssel-Wert-Speicherung (wie localStorage, aber native)

3. Initialisiere Capacitor mit deinen Projekt-Daten:

bunx cap init my-app com.example.myapp --web-dir .output/public

Ersetze my-app mit deinem App-Namen und com.example.myapp mit deiner App-ID (umgekehrte Domänennotation).

4. Erstelle oder aktualisiere das capacitor.config.ts Datei mit der richtigen Konfiguration:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

5. Install native Platforms:

bun add @capacitor/ios @capacitor/android

6. Fügen Sie die Ordner für die native Plattformen hinzu:

bunx cap add ios
bunx cap add android

Capacitor wird die ios und android Ordner am Root Ihres Projekts erstellen, die die native Projekte enthalten.

Um das Android-Projekt zu bauen, benötigen Sie Android Studio. Für iOS benötigen Sie einen Mac mit Xcode.

7. Bauen und synchronisieren Sie Ihr Projekt:

bun run mobile

Dies läuft Ihren benutzerdefinierten Skript aus, das die statische Nuxt-Build erzeugt und die Dateien mit den native Plattformen synchronisiert.

Erstellen und Bereitstellen von native Apps

Um Ihre native mobile App zu erstellen und zu deployen, folgen Sie diesen Schritten:

Um iOS-Apps zu entwickeln, müssen Sie Xcode installiert haben, und für Android-Apps müssen Sie Android Studio installiert haben. Darüber hinaus müssen Sie, wenn Sie Ihre App im App Store verteilen möchten, sich für iOS im Apple Developer Programm und für Android im Google Play Console anmelden.

1. Öffnen Sie die native Projekte:

Für iOS:

bun run mobile:ios

Für Android:

bun run mobile:android

Oder direkt mit Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Die App erstellen und ausführen:

• In Android Studio wartet man auf das Projekt, und klickt dann auf den „Ausführen“-Button, um die App auf einem verbundenen Gerät oder Emulator zu deployen.

• In Xcode, stell deine Signierungskonto ein, um die App auf einem echten Gerät zu deployen. Wenn du das noch nicht gemacht hast, wird Xcode dich durch den Prozess führen (hierfür musst du Mitglied des Apple Developer Program sein). Sobald du eingerichtet hast, klickst du auf den „Spiel“-Button, um die App auf deinem verbundenen Gerät auszuführen.

Herzlichen Glückwunsch! Du hast deine Nuxt-Web-App erfolgreich auf einem mobilen Gerät deployt.

Aber halt, es gibt auch eine schnellere Möglichkeit, dies während der Entwicklung zu tun…

Capacitor Live Reload

Während der Entwicklung kannst du von Live Reloaden profitieren, um Änderungen sofort auf deinem mobilen Gerät zu sehen. Um diese Funktion zu aktivieren, folge diesen Schritten:

1. Finde deine lokale IP-Adresse:

• Auf macOS, führe folgenden Befehl in der Terminal-Anwendung aus:

  ipconfig getifaddr en0

• Auf Windows, führe:

  ipconfig

  Suche nach der IPv4-Adresse in der Ausgabe.

2. Aktualisieren Sie Ihre capacitor.config.ts auf Ihre Entwicklungsserver zuweisen:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... your plugin config
  },
};

export default config;

Ersetzen Sie YOUR_IP_ADDRESS mit Ihrer lokalen IP-Adresse (z.B. 192.168.1.100).

3. Die

bunx cap copy

Anweisung kopiert das Web-Ordner und Konfigurationsänderungen in das native Projekt ohne Aktualisierung des gesamten Projekts. copy Starten Sie Ihren Nuxt Dev Server und rebuilden Sie in Xcode/Android Studio:

4. Jetzt werden alle Änderungen an Ihrer Nuxt App automatisch neu geladen, um diese zu spiegeln.

bun run dev

Hinweis:

Wenn Sie neue Plugins installieren oder Änderungen an native Dateien vornehmen, müssen Sie das native Projekt neu erstellen, da live-Reload nur auf Web __CAPGO_KEEP_0__-Änderungen anwendbar ist. Mit code-Plugins nutzen.

Capacitor ist nur für Web-Änderungen verfügbar.

Capacitor Plugins ermöglichen Ihnen, Zugriff auf native Gerätefeatures aus Ihrer Nuxt-Anwendung zu erhalten. Lassen Sie uns herausfinden, wie man den Teilen-Plugin als Beispiel verwendet:

1. Installieren Sie das Teilen-Plugin:

bun add @capacitor/share

2. Erstellen oder aktualisieren Sie eine Seite, um das Teilen-Plugin zu verwenden. In Nuxt 4 gehen Seiten in app/pages/:

<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
    <button
      @click="shareContent"
      class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
    >
      Share now!
    </button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function shareContent() {
  await Share.share({
    title: 'Check this out!',
    text: 'Built with Nuxt and Capacitor',
    url: 'https://capacitorjs.com',
    dialogTitle: 'Share with friends',
  });
}
</script>

3. Synchronisieren Sie die Änderungen mit dem native Projekt:

bun run mobile

Oder synchronisieren Sie ohne Wiederaufbau:

bunx cap sync

4. Wiederaufbauen und die App auf Ihrem Gerät ausführen.

Jetzt, wenn Sie auf den „Jetzt teilen!“-Button klicken, erscheint das native Teilen-Dialogfeld.

Als Nächstes können Sie die App auf iOS und Android mit Capgo Navigation und Übergängen noch nativer anfühlen lassen und häufige iOS-Anzeige-Layoutprobleme lösen, die zu horizontaler Überlauf oder gekürzten sicheren Bereichen führen.

Natürlicher Anzeige-UI mit Capgo Native Navigation und Übergängen

Ich habe in den letzten Jahren mit Ionic um cross-plattform-Anwendungen zu erstellen, aber die Integration mit Nuxt ist umständlich und selten lohnenswert, wenn Sie bereits haben Tailwind CSS.

Für einen nativen mobilen Look in einer Nuxt + Capacitor-Anwendung verwenden Sie stattdessen Capgo-Plugins anstelle von web-only UI-Kits wie Konsta UI:

• @capgo/capacitor-native-navigation — nativer Navbar, Liquid Glass-Tastenleiste auf iOS und eine verschwommene Tastenleiste-Style auf Android. Der Nuxt-Router hält die Routenstatus; der Plugin besitzt die native Chrome.
• @capgo/capacitor-transitions — Ionic-Style-Seitenübergänge und iOS-Rückwärts-Schub auf der WebView-Schicht, ohne Ionic-UI zu übernehmen.

Installieren Sie beide:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Konfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit Web-Inhalt die native Balken respektiert:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendern Sie eine Liquid Glass-Tastenleiste (iOS verwendet die Systemeigene Rendering; Android verwendet eine verschwommene WebView-Hintergrund):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

Fügen Sie native Seitenübergänge in Ihrem App-Shell hinzu:

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';

initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
  }
});

const openSettings = () => {
  setDirection('forward');
  router.push('/settings');
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <router-view />
  </cap-router-outlet>
</template>

Wie Sie Seiten mit Routen umschließen cap-router-outlet, cap-page, und cap-content, und aufrufen setDirection('forward') oder setDirection('back') vor der Navigation. Duplikate Web-Über- und Fußzeilen, wenn native Navigation diese Oberflächen besitzt.

Siehe die vollständigen Anleitungen: Verwenden Sie @capgo/capacitor-native-navigation und Verwenden Sie @capgo/capacitor-transitions.

Sichere Bereiche mit Tailwind

Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Hilfsfunktionen und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

In app/assets/css/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Für Nuxt 4 mit Tailwind CSS 4, behalten Sie diese Import in der CSS-Datei bei, die von nuxt.config.ts.

Verwenden Sie Hilfsfunktionen wie pt-safe, pb-safe, und px-safe anstatt env(safe-area-inset-*) manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Nuxt-Konfiguration fehlt, öffnen Sie ein PR auf GitHub.

iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontale Überschreitung)

Wenn Inhalte gekürzt, verschoben oder horizontal scrollbar auf iOS aussehen, fügen Sie mehr overflow-x: hidden oder das viewport-Tag alleine anpasst, hilft normalerweise nicht. Arbeiten Sie durch diese Überprüfungen in der Reihenfolge.

Stellen Sie sicher, dass die viewport-Metatag korrekt angewendet wird

Innerhalb von nuxt.config.ts, setzen Sie das viewport über app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

Behandeln Sie die iOS-Sicherheitszone von einem einzigen Root-Wrapper aus

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort die Sicherheitszone-Padding an — nicht in mehreren verschachtelten Komponenten:

html,
body,
#__nuxt {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

Umgeben Sie alle Seiteninhalte innerhalb von .app-shell. Doppelte Sicherheitszone-Padding in Kopfzeilen, Modalen und Layout-Wrappern macht die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

Mit @capgo/tailwind-capacitor, können Sie denselben Padding mit Hilfsmitteln wie pt-safe pb-safe px-safe auf diesem einzelnen Shell.

Set Capacitor iOS auf contentInset zu never erst

In capacitor.config.tspräferieren Sie native inset deaktivieren und lassen Sie CSS (oder Native Navigation’s) contentInsetMode: 'css'den sicheren Bereich besitzen:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

Mischen Sie Capacitor’s automatische Inhalts-Einrastung mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppeltes Abstand.

Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das 100vwTailwind w-screeneine feste Pixelbreite verwendet oder eine große min-width.

In Safari Web Inspector, führen Sie Folgendes aus:

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

Mit Tailwind ersetzen Sie w-screen mit w-full sofern möglich. Viele horizontale Überlaufprobleme rühren daher 100vw / w-screen, duplizierte sichere Bereiche oder ein fester Breitencontainer — nicht vom Viewport-Meta-Tag selbst.

Fazit

Sie haben erfolgreich Ihre bestehende Nuxt-Webanwendung in native iOS- und Android-Anwendungen umgewandelt, indem Sie Capacitor 8 einsetzten. Ihre Vue-Codebasis läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräteeingaben.

Was Sie erreicht haben:

• Konfiguriert Nuxt für statische Generierung
• Hinzugefügt Capacitor 8 mit wesentlichen Plugins
• Erstellt und bereitgestellt auf iOS- und Android-Emulatoren
• Hat live Reload für Entwicklung aktiviert
• Gemeinsame iOS-Layoutprobleme wurden behoben (viewport, sichere Fläche, Überlauf)
• Hinzugefügt wurde eine native anfühlsende Benutzeroberfläche mit Capgo Native Navigation und Transitions

Nächste Schritte:

• Einrichten Capgo für über das Internet erfolgende Updates ohne Wiederabgabe im App-Store
• Mehr native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzufügen
• Konfigurieren Sie App-Icons und Splash-Screens für die Produktion
• Stellen Sie Ihr App für die Einreichung im App Store und Google Play vor

Ein neues Projekt starten? Überprüfen Sie Ein Nuxt Mobile App von Grund auf aufbauen für eine umfassende Anleitung.

Ressourcen

• Nuxt-Dokumentation
• Capacitor 8 Dokumentation
• @capgo/capacitor-native-Navigation — Glasartige Tab-Leiste und nativer Chrome
• @capgo/capacitor-Übergänge — Übergänge, die wie auf einem nativen Gerät fühlen
• @capgo/tailwind-capacitor — Tailwind-sichere Bereiche für Capacitor
• Capgo - Live-Updates für Capacitor-Apps

Erhalten Sie Informationen darüber, wie Capgo Ihnen helfen kann, bessere Apps schneller zu entwickeln, Registrieren Sie sich für ein kostenloses Konto Heute.

Bleiben Sie bei Convert Your Nuxt App zu iOS & Android mit Capacitor 8

Wenn Sie Convert Your Nuxt App zu iOS & Android mit Capacitor 8 um native Plugin-Arbeit zu planen, verbinden Sie es mit Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, Ionic Enterprise Plugin Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen und Capgo Native Builds für das Produktworkflow in Capgo Native Builds.