Ihr Nuxt-App auf iOS & Android mit Capacitor 8 umwandeln

Einführung

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

Capacitor umhüllt Ihre Web-App in einem nativen Container, wodurch Ihnen Zugriff auf Geräteeinstellungen wie Kamera, Dateisystem und Push-Benachrichtigungen gewährt wird, 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 unverändert weiter.

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-Simulatoren
• Aktivieren Sie die Live-Reload-Funktion für eine schnellere Entwicklung
• Beheben Sie häufige iOS-Anzeigeprobleme (viewport, sichere Fläche, horizontale Überlauf)
• Fügen Sie natürliche Anzeige mit Capgo Native Navigation und Transitions hinzu

Sind Sie auf der Suche nach einem neuen Projekt von Grund auf? Überprüfen Sie unsere Anleitung zu Erstellung einer mobilen Nuxt-Anwendung von Grund auf.

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.
• Native 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 (für die iOS-Entwicklung, nur macOS)
• Android Studio (für die Android-Entwicklung)

Konfigurieren Sie Ihre Nuxt-Anwendung für Mobilgeräte

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

Stellen Sie sicher, dass Ihre 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 umbauen.

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 Splashschirm verwalten
• @capacitor/Statusleiste: Die Geräte-Statusleiste anpassen
• @capacitor/Einstellungen: Schlüssel-Wert-Speicher (wie localStorage, aber native)

3. Capacitor mit Ihren Projekt-Daten initialisieren:

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

Ersetzen my-app durch Ihren App-Namen und com.example.myapp durch Ihre App-ID (umgekehrte Domänennotation).

4. Erstellen oder aktualisieren Sie 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 folgenden Ordner am Root Ihres Projekts erstellen, die die native Projekte enthalten. ios und android Ordner am Root Ihres Projekts, 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, benötigen Sie Xcode installiert, und für Android-Apps benötigen Sie Android Studio installiert. Darüber hinaus benötigen Sie, wenn Sie Ihre App im App Store verteilen möchten, die Anmeldung im Apple Developer Programm für iOS und im Google Play Console für Android.

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, warten Sie, bis das Projekt bereit ist, und klicken Sie dann auf die Schaltfläche „Ausführen“ zum Bereitstellen der App auf einem verbundenen Gerät oder einem Emulator.

• In Xcode, konfigurieren Sie Ihr Signierungskonto, um die App auf einem realen Gerät bereitzustellen. Wenn Sie dies noch nicht getan haben, führt Xcode Sie durch den Prozess (beachten Sie, dass Sie sich im Apple Developer Programm anmelden müssen). Sobald Sie eingerichtet sind, klicken Sie auf die Schaltfläche „Abspielen“ zum Ausführen der App auf Ihrem verbundenen Gerät.

Glückwunsch! Sie haben Ihre Nuxt-Web-App erfolgreich auf einem mobilen Gerät bereitgestellt.

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

Capacitor Live Reload

Während der Entwicklung können Sie von Live-Reloaden profitieren, um Änderungen sofort auf Ihrem mobilen Gerät zu sehen. Um diese Funktion zu aktivieren, folgen Sie diesen Schritten:

1. Finden Sie Ihre lokale IP-Adresse:

• Auf macOS führen Sie den folgenden Befehl im Terminal aus:

  ipconfig getifaddr en0

• Auf Windows führen Sie:

  ipconfig

  Suchen Sie nach der IPv4-Adresse in der Ausgabe.

2. Aktualisieren Sie Ihren capacitor.config.ts auf Ihren 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. Anwenden Sie die Änderungen an Ihrem nativen Projekt:

bunx cap copy

Die copy Befehl kopiert das Web-Ordner und die Konfigurationsänderungen in das nativ Projekt ohne Aktualisierung des gesamten Projekts.

4. Starten Sie Ihren Nuxt Dev-Server und erneuern Sie in Xcode/Android Studio:

bun run dev

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

Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an nativen Dateien vornehmen, müssen Sie das nativ Projekt neu erstellen, da die lebendige Wiedergabe nur auf Web-code-Änderungen anwendbar ist.

Verwenden Sie Capacitor-Plugins

Capacitor Plugins ermöglichen Ihnen, Zugriff auf native Gerätefunktionen von Ihrem Nuxt-App 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 Wiederverbauen:

bunx cap sync

4. Wiederverbauen und auf Ihrem Gerät ausführen.

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

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-Layout-Probleme lösen, die zu horizontaler Überlauf oder gekürzten sicheren Bereichen führen.

Natürlicher Anzeige-Layout 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 hackig und selten wertvoll, 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ückgabetaste auf der Edge-Swipe-Ebene, 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 das 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>

Routenverlaufene Seiten in cap-router-outlet, cap-pageund cap-contentund aufrufen setDirection('forward') oder setDirection('back') bevor Sie navigieren. Duplikate Web-Über- oder Fußzeilen, wenn native Navigation diese Oberflächen besitzt.

Siehe die vollständigen Anleitungen: Mit @capgo/capacitor-native-navigation und Mit @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 Hilfsmittel 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 Hilfsmittel 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 Überschuss)

Wenn Inhalte gekürzt, verschoben oder horizontal scrollbar auf iOS aussehen, fügen Sie mehr overflow-x: hidden oder das Anpassen der viewport-Tags allein reicht in der Regel nicht aus. Arbeiten Sie durch diese Überprüfungen in der Reihenfolge.

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

In nuxt.config.ts, setzen Sie die 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-Sicherheitsbereiche von einem einzigen Root-Wrapper aus

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort die Sicherheitsbereichsabstände 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);
}

Umwickeln Sie alle Seiteninhalte innerhalb .app-shellDoppelte Sicherheitsbereichsabstände in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aus.

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

Setzen Sie Capacitor iOS auf contentInset auf never erst

In capacitor.config.ts, bevorzugt native inset deaktivieren und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') das sichere Bereich besitzen:

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

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

Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, einen fixen Pixelbreite oder eine große min-width.

In Safari Web Inspector, ausführen:

[...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 wenn möglich. Viele horizontale Überlaufprobleme kommen von 100vw / w-screen, dupliziertem sicheren Bereichsabstand oder einem festsitzenden Container — nicht von der Viewport-Meta-Tags selbst.

Zusammenfassung

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

Was Sie erreicht haben:

• Nuxt für statische Generierung konfiguriert
• Hinzugefügt Capacitor 8 mit wesentlichen Plugins
• Aufgebaut und auf iOS- und Android-Emulatoren bereitgestellt
• Lebendes Wiedergeben für Entwicklung aktiviert
• Gemeinsame iOS-Layoutprobleme wurden gelöst (viewport, sichere Bereich, Überlauf)
• Ermöglicht 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
• Fügen Sie weitere native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzu
• Konfigurieren Sie App-Icons und Splash-Screens für die Produktion
• Vorbereiten Sie Ihre App für die Einreichung im App Store und bei Google Play

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

Ressourcen

• Nuxt-Dokumentation
• Capacitor 8 Dokumentation
• @capgo/capacitor-native-Navigation — Glasartige Liquid-Tastebar und native Chrome
• @capgo/capacitor-Übergänge — Übergänge mit natürlicher Seite
• @capgo/tailwind-capacitor — Tailwind-sichere-Bereichs-Utilities für Capacitor
• Capgo - Live-Updates für Capacitor-Apps

Erhalten Sie Informationen darüber, wie Capgo Ihnen helfen kann, bessere Apps schneller zu erstellen, sich für ein kostenloses Konto anmelden 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 Alternativen zu Ionic Enterprise Plugin für das Produktworkflow in Ionic Enterprise Plugin Alternativen und Capgo Native Builds für das Produktworkflow in Capgo Native Builds.