Convertieren Sie Ihre Next.js App in iOS- und Android-Apps mit Capacitor 8

Einführung

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

Capacitor umhüllt Ihre Web-App in einem nativen Container, der Ihnen Zugriff auf Geräteeinrichtungen wie Kamera, Dateisystem und Push-Benachrichtigungen bietet, während Ihre bestehende React-Codebasis erhalten bleibt. Im Gegensatz zu React Native müssen Sie nichts umschreiben – Ihre Next.js code läuft unverändert.

Was Sie lernen werden:

Konfigurieren Sie Ihre bestehende Next.js-App für statische Exportierung
Fügen Sie Capacitor 8 mit wesentlichen nativen Plugins hinzu
Bauen und testen Sie auf iOS- und Android-Emulatoren
Aktivieren Sie Live-Reload für eine schnellere Entwicklung
Beheben Sie häufige iOS-Anzeigeprobleme (Ansicht, sichere Fläche, horizontale Überlauf)
Fügen Sie natürliche Anzeige mit Capgo Native Navigation und Transitions hinzu

Sind Sie an einem neuen Projekt von vorne loslegen? Überprüfen Sie unsere Anleitung zu Die Erstellung einer mobilen App mit Next.js von Grund auf.

Vorteile der Verwendung von Next.js und Capacitor

Code WiederverwendbarkeitMit Next.js kannst du wiederverwendbare Komponenten schreiben und code zwischen deiner Web- und mobilen App teilen, was Entwicklungzeit und -anstrengung spart.
LeistungNext.js bietet integrierte Leistungsoptimierungen, wie z.B. Server-Seiten-Rendern und code-Splitting, um schnelle Ladezeiten und eine glatte Benutzererfahrung zu gewährleisten.
Nativ-Features: Next.js bietet integrierte Leistungsoptimierungen wie Server-Seiten-Rendern und Capacitor-Splitting, um schnelle Ladezeiten und eine glatte Benutzererfahrung sicherzustellen.
Einfache Entwicklung: Capacitor bietet Zugriff auf nativgerüstete Gerätefunktionen wie die Kamera, die Geolocation und mehr, um Ihnen die Möglichkeit zu geben, featurereiche Mobilanwendungen zu erstellen.

Prerequisites

Before you begin, make sure you have:

Voraussetzungen installed
Ein bestehendes Next.js 15+ Anwendung
Xcode (für iOS-Entwicklung, macOS nur)
Android Studio (für Android-Entwicklung)

Konfiguration Ihrer Next.js-Anwendung für Mobilgeräte

Der erste Schritt besteht darin, Ihre Next.js-Anwendung für die statische Exportierung zu konfigurieren. Capacitor benötigt statische HTML/JS/CSS-Dateien, um sie in die native App zu packen.

Öffnen Sie Ihr next.config.js (oder next.config.tsDatei und fügen Sie die Export-Konfiguration hinzu:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

Die output: 'export' Die Einstellung erzählt Next.js, statische HTML-Dateien zu generieren. images: { unoptimized: true } bypasses Next.js-Bildoptimierung, die einen Server erfordert.

Wichtig: If you’re using features that require a server (API routes, server components with data fetching, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Hinzufügen von mobilen-Skripten zu Ihrem package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Teste die statische Exportierung mit:

bun run build

Sie sollten ein out Ordner am Root Ihres Projekts sehen. Dies enthält alle statischen Dateien, die Capacitor in Ihre native App einbündeln wird.

Capacitor 8 zu Ihrem Projekt hinzufügen

Um Ihre Next.js-Anwendung in eine native mobile Container zu packen, folgen Sie diesen Schritten:

Installieren Sie Capacitor-Core und CLI:

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

Installieren Sie gängige Capacitor-Plugins, die Sie benötigen:

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

Diese Plugins liefern wichtige Funktionen:

capacitor/app: Verwalte App-Lebenszyklus-Ereignisse (Vordergrund/Hintergrund, URLs)
capacitor/keyboard: Kontrolliere die Tastaturverhalten auf Mobilgeräten
capacitor/splash-screen: Verwalte die native Splash-Screen
capacitor/preferences: Speichere Schlüssel-Wert-Daten persistent

Initialisiere Capacitor mit Ihren Projekt-Daten:

bunx cap init my-app com.example.myapp --web-dir out

Ersetzen Sie my-app mit Ihrem App-Namen und com.example.myapp mit Ihrer App-ID (umgekehrte Domänennotation).

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: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true,
    },
  },
};

export default config;

Installieren Sie native Plattformen:

bun add @capacitor/ios @capacitor/android

Fügen Sie die native Plattformordner hinzu:

bunx cap add ios
bunx cap add android

Capacitor wird die ios und android Ordner an der Wurzel 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.

Projekt erstellen und synchronisieren:

bun run mobile

Dies läuft Ihren benutzerdefinierten Skript aus, das das Next.js-Projekt erstellt und die statischen Dateien mit den nativen Plattformen synchronisiert.

Erstellung und Bereitstellung von nativen Apps

Um eine native mobile App zu erstellen und zu deployen, folgen Sie bitte diesen Schritten: Um iOS-Apps zu entwickeln, benötigen Sie Xcode installiert und für Android-Apps benötigen Sie Für Android: installed. Moreover, if you plan to distribute your app on the app store, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android.

Öffnen Sie die native Projekte:

Android Studio

bun run mobile:ios

Apple Developer Programm

bun run mobile:android

Direkt mit Capacitor CLI.

bunx cap open ios
bunx cap open android

Entwickeln und ausführen Sie die App:

android-studio-run

In Android Studio warten Sie, bis das Projekt bereit ist, und klicken Sie dann auf die Schaltfläche "Ausführen", um die App auf einem verbundenen Gerät oder einem Emulator zu deployen.
In Xcode stellen Sie Ihr Signierkonto ein, um die App auf einem echten Gerät zu deployen. Wenn Sie dies noch nicht getan haben, wird Xcode Sie durch den Prozess führen (beachten Sie, dass Sie sich im Apple Developer Programm anmelden müssen). Sobald Sie eingerichtet sind, klicken Sie auf die Schaltfläche "Spiel" und führen Sie die App auf Ihrem verbundenen Gerät aus.

Herzlichen Glückwunsch! Sie haben erfolgreich Ihre Next.js-Web-App auf einem mobilen Gerät deployt.

Aber warten Sie, es gibt auch eine schnellere Möglichkeit, dies während der Entwicklung zu tun...

Capacitor Capacitor Live Reload

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

Finden Sie Ihre lokale IP-Adresse:

Auf macOS führen Sie den folgenden Befehl in der Terminal-Anwendung aus:
```
ipconfig getifaddr en0
```
On Windows, führen Sie Folgendes aus:
```
ipconfig
```
Suchen Sie nach der IPv4-Adresse in der Ausgabe.

Aktualisieren Sie capacitor.config.ts um auf Ihren Entwicklungsserver zu zeigen:

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

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

export default config;

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

Anwenden Sie die Änderungen an Ihrem nativen Projekt:

bunx cap copy

Die copy Befehl kopiert das Web-Ordner und die Konfigurationsänderungen in das native Projekt ohne das gesamte Projekt zu aktualisieren.

Rebuild und führen Sie die App auf Ihrem Gerät mit Android Studio oder Xcode aus.

Jetzt werden die Änderungen an Ihrer Next.js App automatisch in der mobilen App aktualisiert, sobald Sie sie vorgenommen haben.

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

Mit Capacitor-Plugins

Capacitor-Plugins ermöglichen Ihnen, Zugriff auf native Gerätefunktionen von Ihrem Next.js-Anwendungscode zu erhalten. Lassen Sie uns sehen, wie man den Share-Plugin als Beispiel verwendet:

Installieren Sie den Share-Plugin:

bun add @capacitor/share

Aktualisieren Sie pages/index.js Datei, um den Share-Plugin zu verwenden:

import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';

export default function Home() {
  const share = async () => {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends',
    });
  };

  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href="https://nextjs.org">Capgo!</a>
        </h1>

        <p className={styles.description}>
          <h2>Cool channel</h2>
          <button onClick={() => share()}>Share now!</button>
        </p>
      </main>
    </div>
  );
}

Synchronisieren Sie die Änderungen mit dem native Projekt:

Wie bereits erwähnt, müssen wir bei der Installation neuer Plugins eine Synchronisierungsoperation durchführen und das App dann auf unserem Gerät neu bereitstellen. Um dies zu tun, führen Sie den folgenden Befehl aus:

bun run mobile

Oder synchronisieren Sie ohne Neuberechnung:

bunx cap sync

Rebuild und führen Sie die App auf Ihrem Gerät aus.

Jetzt, wenn Sie auf den Button „Jetzt teilen!“ klicken, erscheint das native Teilen-Dialogfeld, sodass Sie den Inhalt mit anderen Apps teilen können.

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas. ## Native-feeling UI with Capgo Native Navigation and Transitions

## Eine natürliche Benutzeroberfläche mit __CAPGO_KEEP_1__ Native Navigation und Übergängen Ionic Um cross-plattform-Anwendungen zu erstellen, aber die Integration mit Next.js ist umständlich und selten lohnenswert, wenn man bereits } Tailwind CSS 4.

Für einen nativen mobilen Look in einer Next.js + Capacitor App verwenden Sie stattdessen Capgo-Plugins anstatt web-basierter UI-Kits wie Konsta UI.

@capgo/capacitor-native-Navigation — native navbar, Liquid Glass tab bar on iOS, and a blurred tab bar style on Android. Your Next.js router keeps route state; the plugin owns the native chrome.
@capgo/capacitor-Übergänge — Seitenübergänge im Ionic-Stil und iOS-Rück-Back-Touch in der WebView-Schicht, ohne Ionic-UI zu übernehmen.

Install beide:

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

Konfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit Webinhalte die native Balken respektieren:

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

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

Rendern Sie eine Glass-Liquid-Tasteleiste (iOS verwendet die Systemeigene Rendering; Android verwendet einen verschwommenen 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:

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

Umfasst die gerouteten Seiten in cap-router-outlet, cap-pageund cap-contentund rufen Sie setDirection('forward') oder setDirection('back') vorher router.push() oder router.back(). Machen Sie sich keine Sorgen, dass Sie Web-Überkopf-Elemente duplizieren, wenn native Navigation diese Oberflächen besitzt.

Sehen Sie sich die vollständigen Anleitungen an: Verwenden Sie @capgo/capacitor-native-navigation und Using @capgo/capacitor-Übergänge.

Sichere Bereiche mit Tailwind

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

bun add -D tailwind-capacitor

In styles/globals.css:

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

Verwenden Sie Hilfsmittel wie pt-safe, pb-safe, und px-safe anstatt, sie zu verstreuen env(safe-area-inset-*) per Hand. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Next.js-Konfiguration fehlt, Öffnen Sie einen PR auf GitHub.

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

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

Stellen Sie sicher, dass die Viewport-Metatag korrekt angewendet wird.

export) (app/von viewport Pages Router app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

): Setzen Sie den Viewport-Metatag in (pages/): setze das Viewport-Metatag ein pages/_app.tsxviewport _document.tsx (Next.js mag keine Tags von) _document.tsx wie Sie es für die Ansicht erwartet.

Verwende das iOS-Safe-Area nur von einem Root-Wrapper aus.

Erstellen Sie eine einzelne App-Shell und fügen Sie dort Sicherheitsbereich-Puffer an – nicht in mehreren verschachtelten Komponenten:

html,
body,
#__next {
  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);
}

Verwenden Sie . um alle Seiteninhalte einzuschließen .app-shellDoppelte Sicherheitsbereich-Puffer in Kopfzeilen, Modalen und Layout-Wrapper machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.

With @capgo/tailwind-capacitorSie können denselben Padding auch mit Hilfsfunktionen ausdrücken. pt-safe pb-safe px-safe auf dieser einzelnen Shell.

Set Capacitor iOS `contentInset` to `never` erste

In capacitor.config.ts, bevor Sie native Einstellungen deaktivieren und lassen Sie CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Fläche besetzen:

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

Die Mischung von Capacitor’s automatischer Inhalts-Einstellung mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.

Finden Sie das überlaufende Element

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

In Safari Web Inspector, führen Sie 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 wenn möglich. Viele horizontale Überschreitung von Problemen kommen von 100vw / w-screen, dupliziertes sicherer Bereich Puffer, oder ein fester Breite Container — nicht von der Ansicht Meta-Tag selbst.

Leistungsoptimierung

Um die optimale Leistung Ihres Next.js und Capacitor Apps sicherzustellen, beachten Sie die folgenden Best Practices:

Kleinhalten Sie die App-Größe, indem Sie nicht benötigte Abhängigkeiten und Assets entfernen.
Optimieren Sie Bilder und andere Medien-Dateien, um die Ladezeiten zu reduzieren.
Implementieren Sie lazy Loading für Komponenten und Seiten, um die Initial-Lade-Leistung zu verbessern.
Verwenden Sie serverseitige Rendering (SSR) mit Next.js, um die App-Lade-Geschwindigkeit und die Suchmaschinen-Optimierung (SEO) zu verbessern.
Nutzen Sie Capacitor-integrierte Optimierungen, wie z.B. das Caching des Web-Views und das App-Bündeln.

Zusammenfassung

Ihre Web-Anwendung wurde erfolgreich in native iOS- und Android-Apps umgewandelt, indem Sie Capacitor 8 verwendet haben. Ihre Web-Codebasis läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräte-APIs.

Was Sie erreicht haben:

Next.js für statische Exporte konfiguriert
Capacitor 8 mit wichtigen Plugins hinzugefügt
Für iOS- und Android-Emulatoren erstellt und bereitgestellt
Live-Reload für Entwicklung aktiviert
Gängige iOS-Anzeigeeinblendungen (viewport, sichere Fläche, Überfluss) behoben
Mit Capgo Native Navigation und Transitions eine natürliche Benutzeroberfläche hinzugefügt

Nächste Schritte:

Einrichten Capgo für über-ein-Netz-Updates ohne App-Store-Wiederabgabe
Mehr native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzufügen
Konfigurieren Sie App-Ikonen und Splash-Screens für die Produktion
Vorbereiten Sie Ihre App für die Einreichung bei App Store und Google Play

Neue Projektidee? Überprüfen Sie Ein Next.js-Mobilanwendung von Grund auf bauen für eine umfassende Anleitung.

Ressourcen

Next.js-Dokumentation
@capgo/capacitor-native-Navigation — Liquid Glass-Tastenleiste und native Chrome
Capacitor 8 Dokumentation
@capgo/capacitor-Übergänge — native anfühlfende Seitenübergänge
@capgo/tailwind-capacitor — Tailwind-Sicherheitsbereichs-Utility-Funktionen für Capacitor
Capgo - Live-Updates für Capacitor-Apps

Lernen Sie, wie Capgo Ihnen helfen kann, bessere Apps schneller zu bauen Registrieren Sie sich für ein kostenloses Konto heute.

Fahren Sie mit der Umwandlung Ihres Next.js-Apps in iOS- und Android-Apps mit Capacitor 8 fort

Wenn Sie bereits Konvertieren Sie Ihre Next.js App in iOS- und Android-Anwendungen mit Capacitor 8 für den Produktworkflow in __CAPGO_KEEP_0__-Plugin-Verzeichnis Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo Plugins hinzufügen oder aktualisieren zur Implementierungsdetail in Plugins hinzufügen oder aktualisieren Ionische Unternehmens-Plugin-Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen, und Capgo nativee native Builds zum Produktworkflow in Capgo Native Builds.

Konvertieren Sie Ihre Next.js-Anwendung in iOS- & Android-Apps mit Capacitor 8