Bauen Sie eine Next.js-Mobilanwendung von Grund auf mit Capacitor 8

Einführung

Möchten Sie eine mobile App mit Next.js von Grund auf erstellen? Diese Anleitung führt Sie durch das Erstellen eines brandneuen Next.js 15-Projekts, das von Anfang an für mobile Entwicklung konfiguriert ist, und das dann als native iOS- und Android-Apps verpackt wird mit Capacitor 8.

Am Ende dieses Tutorials haben Sie eine funktionierende mobile App, die auf Simulatoren läuft, die Sie weiterentwickeln und schließlich auf dem App Store und Google Play veröffentlichen können.

Zeitbedarf: ~30 Minuten

Was Sie bauen werden:

Einen neuen Next.js 15-Projekt mit App Router
Statik Export-Konfiguration für mobile Geräte
Capacitor 8 mit wichtigen Plugins
Native iOS- und Android-Anwendungen
Live-Reload-Entwicklungssetup

Sie haben bereits eine Next.js-Anwendung? Überprüfen Sie stattdessen Konvertieren Sie Ihre Next.js-Anwendung in eine mobile Anwendung anstatt.

Voraussetzungen

Stellen Sie sicher, dass Sie diese installiert haben:

Node.js 18+ (überprüfen Sie mit node --version)
Bun Paketmanager (curl -fsSL https://bun.sh/install | bash)
Xcode (nur für macOS, für iOS-Entwicklung)
Android Studio (für Android-Entwicklung)

Schritt 1: Erstellen Sie ein neues Next.js-Projekt

Beginnen Sie mit der Erstellung eines frischen Next.js 15-Projekts:

bunx create-next-app@latest my-mobile-app

Wenn Sie dazu aufgefordert werden, wählen Sie diese Optionen:

TypeScript: Ja (empfohlen)
ESLint: Ja
Tailwind CSS: Ja (empfohlen für mobile Styling)
src/ Verzeichnis: Ja
App Router: Ja (empfohlen)
Import Alias: Standard (@/*)

Navigieren Sie zu Ihrem Projekt:

cd my-mobile-app

Schritt 2: Konfigurieren Sie Next.js für statische Exporte

Capacitor erfordert statische HTML/JS/CSS-Dateien. Konfigurieren Sie Next.js für statischen Export, indem Sie next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

Warum diese Einstellungen?

output: 'export' — Erzeugt statisches HTML anstatt eine Node.js-Servicerequirement
images: { unoptimized: true } — Deaktiviert die Next.js-Bildoptimierung (erfordert einen Server)
trailingSlash: true — Stellt sicher, dass die Routing in der nativen WebView ordnungsgemäß funktioniert

Schritt 3: Hinzufügen von mobilen Skripten

Aktualisieren Sie Ihr package.json mit mobilen Entwicklungs-Skripten:

{
  "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"
  }
}

Testen Sie die Build:

bun run build

Sie sollten ein out Verzeichnis mit Ihren statischen Dateien.

Schritt 4: Installieren Sie Capacitor 8

Installieren Sie die Kernpaket von Capacitor:

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

Installieren Sie wesentliche Plugins, die die meisten mobilen Apps benötigen:

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

Was diese Plugins tun:

@capacitor/app — Ereignisse im App-Lebenszyklus (Vordergrund/Hintergrund, tiefere Links)
@capacitor/keyboard — Steuern Sie das Tastaturverhalten
@capacitor/splash-screen — Kontrolle des nativen Splash-Screens
@capacitor/status-bar — Die Gerätestatusleiste stylen
@capacitor/vorlieben — Schlüssel-Wert-Speicherung (wie localStorage, aber native)

Schritt 5: Capacitor initialisieren

Capacitor mit Ihren Projekt-Daten initialisieren:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

Ersetzen:

"My Mobile App" mit dem Namen Ihres Anwendungs-Displays
com.example.mymobileapp mit Ihrer App-ID (umgekehrte Domänennotation)

Das erstellt capacitor.config.tsAktualisieren Sie es mit der Plugin-Konfiguration:

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

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

export default config;

Schritt 6: Native Plattformen hinzufügen

Die Plattform-Pakete installieren:

bun add @capacitor/ios @capacitor/android

Erstellen Sie die nativen Projekte:

bunx cap add ios
bunx cap add android

Dies erstellt ios und android Verzeichnisse mit den nativen Projekten.

Schritt 7: Erstellen und Ausführen

Erstellen Sie Ihr Projekt und synchronisieren Sie es mit den nativen Plattformen:

bun run mobile

Öffnen Sie in iOS Simulator:

bun run mobile:ios

Oder Android-Emulator:

bun run mobile:android

In Xcode (iOS):

Wählen Sie einen Simulator aus dem Geräte-Auswahlfeld
Klicken Sie auf die Play-Taste oder drücken Sie Cmd + R

In Android Studio:

Warten, bis Gradle fertig ist, synchronisiert
Einen Emulator aus dem Geräte-Auswahlfeld auswählen
Klicken Sie auf die Ausführungs-Schaltfläche oder drücken Sie Shift + F10

Schritt 8: Live Reload einrichten

Für eine schnellere Entwicklung aktivieren Sie Live Reload, damit Änderungen sofort auf Ihrem Gerät erscheinen.

Ihr lokales IP-Adresse finden:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Eine Entwicklungskonfiguration erstellen: Capacitor hinzufügen zu capacitor.config.ts:

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

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

Den Entwicklungs-Server starten und Konfiguration auf native übertragen:

bun run dev &
NODE_ENV=development bunx cap copy

Neu in Xcode/Android Studio aufbauen

Jetzt werden Änderungen an Ihrem Next.js code auf dem Gerät live neu geladen.

Schritt 9: Erste mobile Bildschirmseite erstellen

Erstellen wir eine einfache, mobilen-freundliche Startseite. Aktualisieren Sie src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

    // Handle back button on Android
    const backHandler = App.addListener('backButton', ({ canGoBack }) => {
      if (!canGoBack) {
        App.exitApp();
      } else {
        window.history.back();
      }
    });

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform">
          Learn More
        </button>
      </div>
    </main>
  );
}

Schritt 10: Fügen Sie die Verarbeitung des sicheren Bereichs hinzu

Mobile Geräte haben Notch, Heimbildschirme und Statusleisten. Fügen Sie die Verarbeitung des sicheren Bereichs mit Tailwind hinzu.

Aktualisieren src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input, textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

Projektstruktur

Ihr Projekt sollte jetzt wie folgt aussehen:

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

Nächste Schritte

Sie haben jetzt eine funktionierende Next.js-Mobilanwendung. Hier sind die nächsten Schritte:

Wichtige Einrichtungen

App-Ikone: Ersetzen Sie die Standardikonen in ios/App/App/Assets.xcassets und android/app/src/main/res
Splash-Screen: Anpassen in native Projekten oder verwenden @capacitor/splash-screen config
Deep Links: Konfigurieren Sie die URL-Schemata für Ihre App

Hinzufügen Sie weitere Funktionen

Kamera: bun add @capacitor/camera
Geolocation: bun add @capacitor/geolocation
Push-Benachrichtigungen: bun add @capacitor/push-notifications
Dateisystem: bun add @capacitor/filesystem

Natives UI und Übergänge verwenden

Verwenden Sie Capgo-Plugins anstelle von Konsta UI für einen nativen mobilen Look:

@capgo/capacitor-native-navigation — Glasartige Tab-Leiste und native Navbar
@capgo/capacitor-Übergänge — Übergänge mit nativem Gefühl

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

Für sichere Bereiche von Tailwind, fügen Sie @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Siehe Verwendung von @capgo/capacitor-native-Navigation, Verwendung von @capgo/capacitor-Übergängeund das tailwind-capacitor-Repo für die Next.js-spezifische Einrichtung.

Lösen von iOS-Layout-Problemen (Viewport, sichere Bereiche und horizontale Überschuss)

If Inhalte scheint gekürzt, verschoben oder horizontal scrollbar auf iOS, fügen Sie mehr oder passen Sie die Ansichtsbeschriftung allein, wird es normalerweise nicht beheben. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass die Ansichtsbeschriftungsmetatag korrekt angewendet wird

App Router

export (app/from viewport Pages Router app/layout.tsx:

import type { Viewport } from 'next';

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

put the viewport meta tag in (pages/not pages/_app.tsxHandle iOS safe area from one root wrapper only _document.tsx.

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

Wrap all page content inside

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);
}

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort die sichere Bereichsabstand an — nicht in mehreren verschachtelten Komponenten: .app-shellDoppelte sichere Bereiche in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aus.

Mit @capgo/tailwind-capacitorkönnen Sie denselben Abstand mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Hülle.

Setzen Sie Capacitor iOS `contentInset` auf `never` erst

In capacitor.config.ts, bevorzugt 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 Inhaltsabstände mit CSS env(safe-area-inset-*) Pufferung ist eine häufige Ursache für doppeltes Abstandspolieren.

Finden Sie das überlaufende Element

Der gewöhnliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine fixe Pixelbreite oder eine große min-width.

In Safari Web Inspector, ausführen Sie:

[...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 bei Bedarf. Viele horizontale Überlaufprobleme kommen von 100vw / w-screen, dupliziertem sicherem Bereichspolieren oder einem fixbreiten Container — nicht von der Viewport-Meta-Tags selbst.

Über-der-Luft-Updates

Einrichten Capgo Um Updates ohne App-Store-Neuveröffentlichung zu pushen:

bunx @capgo/cli init

Fehlerbehebung

Build fehlt mit „Cannot find module“ Ausführen bun install und versuchen Sie es erneut.

iOS: „Kein Signierungsidentität gefunden“ Öffnen Sie Xcode, gehen Sie zu Signing & Capabilities, und wählen Sie Ihr Entwicklungsteam.

Android: „SDK-Ort nicht gefunden“ Erstellen android/local.properties mit sdk.dir=/path/to/android/sdk

Änderungen erscheinen nicht auf dem Gerät Stellen Sie sicher, dass Sie bun run mobile nachdem Sie Änderungen vorgenommen haben. Für Live-Reload überprüfen Sie, ob die IP-Adresse korrekt ist und der Entwicklungs-Server läuft.

Ressourcen

Bereit, Ihre App zu verschicken? Erfahren Sie, wie Capgo Ihnen dabei helfen kann, Updates schneller zu liefern — sich für ein kostenloses Konto anzumelden heute.

Bleiben Sie bei der Erstellung eines mobilen Next.js-Apps von Grund auf mit Capacitor 8

Wenn Sie Die Erstellung einer mobilen Next.js-App von Grund auf mit Capacitor 8 benutzen, um die CI/CD-Automatisierung zu planen, verbinden Sie es mit Capgo CI/CD für den Produktworkflow in Capgo CI/CD, Capgo Native Builds für den Produktworkflow in Capgo Native Builds, Capgo Integrations für den Produktworkflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub Aktionen-Integration für die Implementierungsdetails in GitHub Aktionen-Integration.

Ein Next.js-Mobil-App von Grund auf mit Capacitor 8 erstellen