Einführung
Haben Sie bereits eine Next.js-Webanwendung? In diesem Leitfaden lernen Sie, wie Sie sie in native iOS- und Android-Mobilanwendungen umwandeln können Capacitor 8 — die neueste Version mit verbessertem Leistung und neuen Funktionen.
Capacitor umhüllt Ihre Web-App in eine native Container, wodurch Sie Zugriff auf Geräte-APIs wie Kamera, Dateisystem und Push-Benachrichtigungen erhalten, während Ihre bestehende React-Codebasis beibehalten wird. Im Gegensatz zu React Native müssen Sie nichts umschreiben — Ihre Next.js code läuft wie gewohnt.
Was Sie lernen werden:
- Konfigurieren Sie Ihre bestehende Next.js-Anwendung für statische Export
- Fügen Sie Capacitor 8 mit wichtigen native Plugins hinzu
- Entwickeln und testen auf iOS- und Android-Emulatoren
- Lebendes Wiedergabeverhalten für eine schnellere Entwicklung aktivieren
- Gemeinsame iOS-Anordnungsprobleme (Ansichtsbereich, sichere Fläche, horizontale Überlauf) beheben
- Natürliche Benutzeroberfläche hinzufügen mit Capgo Native Navigation und Transitions
Ein neues Projekt von Grund auf starten? Überprüfen Sie unsere Anleitung zu Erstellung einer mobilen Next.js-Anwendung von Grund auf.
Vorteile der Verwendung von Next.js und Capacitor
- Code-Reusabilität: Next.js ermöglicht Ihnen, wiederholbar zu schreiben Komponenten und code zwischen Ihren Web- und Mobilanwendungen zu teilen, wodurch Entwicklungszeit und -bemühungen eingespart werden.
- Leistung: Next.js bietet integrierte Leistungsoptimierungen, wie z.B. Serverseitiges Rendering und code-Splitting, um schnelle Ladezeiten und eine glatte Benutzererfahrung sicherzustellen.
- Native Funktionen: Capacitor bietet Zugriff auf native Gerätefeatures wie Kamera, Geolocation und mehr, um Ihnen die Möglichkeit zu geben, feature-reiche mobile Apps zu erstellen.
- Simplifizierte Entwicklung: Mit Capacitor können Sie Ihre mobile App mit bekannten Webtechnologien entwickeln und testen, was die Lernkurve reduziert und den Entwicklungsprozess vereinfacht.
Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:
- Node.js 18+ installiert
- Eine bestehende Next.js 15+ Anwendung
- Xcode (für iOS-Entwicklung, macOS nur)
- Android Studio (für Android-Entwicklung)
Ihre Next.js App für Mobile konfigurieren
Der erste Schritt besteht darin, Ihre Next.js App 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.ts) Datei 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' Einstellung erzwingt Next.js, statische HTML-Dateien zu generieren, und images: { unoptimized: true } vermeidet die Next.js-Bildoptimierung, die einen Server erfordert.
Wichtig: Wenn Sie Funktionen verwenden, die einen Server erfordern (__CAPGO_KEEP_0__ Routen, Serverkomponenten mit Datenabrufen usw.), müssen Sie diese um Client-Seitige Alternativen oder externe APIs umstellen. 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.
Fügen Sie mobile-spezifische Skripte Ihrem Projekt hinzu. 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"
}
}Testen Sie die statische Exportierung, indem Sie Folgendes ausführen:
bun run buildSie sollten ein out Ordner im Wurzelverzeichnis Ihres Projekts sehen. Dieser enthält alle statischen Dateien, die Capacitor in Ihre native App einbündeln wird.
Capacitor 8 in Ihrem Projekt hinzufügen
Um Ihre Next.js App in einen nativen mobilen Container zu packen, folgen Sie diesen Schritten:
- Installieren Sie Capacitor-Core und CLI:
bun add @capacitor/core
bun add -D @capacitor/cli- Installieren Sie die gängigen Capacitor-Plugins, die Sie benötigen werden:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesDiese Plugins liefern wichtige Funktionen:
- @capacitor/app: Verwalten Sie Ereignisse im App-Lebenzyklus (Vordergrund/Hintergrund, URLs)
- @capacitor/keyboard: Steuere die Tastaturverhalten auf Mobilgeräten
- @capacitor/splash-screen: Verwalte die native Splash-Screen
- @capacitor/preferences: Speichere Schlüssel-Wert-Daten persistent
- Initialisiere Capacitor mit den Details deines Projekts:
bunx cap init my-app com.example.myapp --web-dir outErsatz my-app mit deinem App-Namen und com.example.myapp mit deinem App-ID (umgekehrte Domänennotation).
- Erstelle oder aktualisiere das
capacitor.config.tsDatei 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;- Installiere native Plattformen:
bun add @capacitor/ios @capacitor/android- Die native Plattform-Ordner hinzufügen:
bunx cap add ios
bunx cap add androidCapacitor wird erstellen ios und android Ordner am Root Ihres Projekts, 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.
- Ihr Projekt bauen und synchronisieren:
bun run mobileDies läuft Ihren benutzerdefinierten Skript aus, das das Next.js-Projekt baut und die statischen Dateien mit den native Plattformen synchronisiert.
Native Apps erstellen und bereitstellen
Um Ihre native mobile App zu erstellen und zu bereitstellen, folgen Sie bitte diesen Schritten: Um iOS-Apps zu entwickeln, benötigen Sie Xcode installiert und für Android-Anwendungen benötigen Sie, dass Android Studio installiert ist. 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.
- Öffnen Sie die native Projekte:
Für iOS:
bun run mobile:iosFür Android:
bun run mobile:androidOder direkt mit Capacitor CLI:
bunx cap open ios
bunx cap open android- 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", um die App auf einem verbundenen Gerät oder einem Emulator zu deployen.
-
In Xcode, Ihre Signierungsaccount einrichten, um die App auf einem echten Gerät zu deployen. Wenn Sie dies noch nicht gemacht haben, wird Ihnen Xcode durch den Prozess führen (beachten Sie, dass Sie sich im Apple Developer Programm angemeldet haben müssen). Sobald Sie eingerichtet haben, klicken Sie auf die "Spiel"-Schaltfläche, um die App auf Ihrem verbundenen Gerät auszuführen.
Herzlichen Glückwunsch! Sie haben Ihre Next.js-Web-App erfolgreich auf einem mobilen Gerät bereitgestellt.
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:
- Finden Sie Ihre lokale IP-Adresse:
-
Bei macOS führen Sie folgenden Befehl im Terminal aus:
ipconfig getifaddr en0 -
Bei Windows führen Sie:
ipconfigSuchen Sie nach der IPv4-Adresse in der Ausgabe.
- Update Ihre
capacitor.config.tsum auf Ihren Entwicklungsserver zu verweisen:
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 durch Ihre lokale IP-Adresse (z.B., YOUR_IP_ADDRESS Die Änderungen auf Ihr natives Projekt anwenden: 192.168.1.100).
- Der
bunx cap copyBefehl kopiert das Web-Ordner und die Konfigurationsänderungen in das natives Projekt ohne das gesamte Projekt zu aktualisieren. copy Rebuild und fahren Sie das App auf Ihrem Gerät mit Android Studio oder Xcode aus.
- Jetzt werden die Änderungen an Ihrer Next.js App automatisch neu geladen, um diese zu spiegeln.
Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an den native Dateien vornehmen, müssen Sie das natives Projekt neu erstellen, da die Live-Neuladung nur auf Web-__CAPGO_KEEP_0__-Änderungen anwendbar ist.
Mit code-Plugins
Capacitor-Plugins ermöglichen Ihnen, Zugriff auf native Gerätefunktionen von Ihrer Next.js App zu erhalten. Lassen Sie uns sehen, wie man das
Capacitor plugins allow you to access native device features from your Next.js app. Let’s explore how to use the als Beispiel verwendet: plugins
- Install den Share-Plugin:
bun add @capacitor/share- Aktualisieren Sie das
pages/index.jsDatei, 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 durchzuführen, führen Sie bitte folgenden Befehl aus:
bun run mobileOder synchronisieren Sie ohne Wiederverwendung:
bunx cap sync- Die App auf Ihrem Gerät neu erstellen und ausführen.
Jetzt, wenn Sie auf den „Jetzt teilen!“-Button klicken, erscheint das native Teilen-Dialogfeld, mit dem Sie den Inhalt mit anderen Apps teilen können.
## Natürlicher Anzeigeeinblendungs-UI mit __CAPGO_KEEP_1__-Native-Navigation und -Übergängen Ich habe bereits seit Jahren mit um cross-plattform-Anwendungen zu erstellen, aber die Integration mit Next.js ist hackig und selten wertvoll, wenn Sie bereits haben Tailwind CSS 4.
Für ein natives Mobil-Design in einer Next.js + Capacitor-Anwendung verwenden Sie Capgo-Plugins anstelle von web-only UI-Kits wie Konsta UI:
- @capgo/capacitor-native-navigations — natives Navigation, Liquid Glass-Tasteleiste auf iOS und eine verschwommene Tasteleiste-Style auf Android. Ihr Next.js-Router hält Routen-Zustand; der Plugin besitzt die native Chrome.
- @capgo/capacitor-Übergänge — Ionic-Style-Seitenübergänge und iOS-Rück-Edge-Swipe in der WebView-Schicht, ohne Ionic-UI zu übernehmen.
Installieren Sie beide:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurieren 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-Tasteleiste (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:
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });Umgehen Sie geroutete Seiten in cap-router-outlet, cap-page, und cap-content, und aufrufen setDirection('forward') oder setDirection('back') vorher router.push() oder router.back(). Wiederholen Sie keine Web-Ober- oder -Unterflächen, wenn native Navigation diese Ober- oder Unterflächen besitzt.
Siehe die vollständigen Anleitungen: Mit @capgo/capacitor-native-Navigation und Mit @capgo/capacitor-Übergänge.
Sichere Bereiche mit Tailwind
Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (als veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Nützlichkeiten und andere Capacitor-freundliche Tailwind-Plugins:
bun add -D tailwind-capacitorIn styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Verwenden Sie Nützlichkeiten wie pt-safe, pb-safe, und px-safe anstatt sie env(safe-area-inset-*) manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt – wenn etwas für Ihre Next.js-Konfiguration fehlt, Öffnen Sie ein PR auf GitHub.
Fixing iOS Layout Issues (Viewport, Safe Area, und Horizontal Overflow)
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 normalerweise nicht aus. Arbeiten Sie durch diese Überprüfungen in der Reihenfolge.
Stellen Sie sicher, dass die viewport-Metatag korrekt angewendet wird
App Router (app/export viewport von app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};Pages Router (pages/export pages/_app.tsxsetzen Sie die viewport-Metatag in _document.tsx , nicht _document.tsx (Next.js mag die Tags nicht auf die Weise anwenden, wie Sie es erwarten, für das Verhalten von viewport).
Behandeln Sie das iOS-Sicherheitsbereich von einem einzigen Root-Wrapper aus
Erstellen Sie ein einzelnes App-Shell und fügen Sie dort Sicherheitsbereich-Padding hinzu — 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);
}Alle Seiteninhalte innerhalb einhüllen .app-shellDoppelte sichere Bereichsabstände in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.
Mit @capgo/tailwind-capacitor, kö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, bevorzugen Sie native Inset deaktiviert 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-*) Ein häufiger Grund für doppelte Abstände ist die Padding.
Finden Sie das überlaufende Element
Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine fixe 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 Überlaufprobleme kommen von 100vw / w-screen, dupliziertem sicherem Abstand oder einem festen Breitencontainer — nicht von der Viewport-Metatag selbst.
Leistungssteigerung
To gewährleisten die beste Leistung Ihres Next.js und Capacitor Apps, beachten Sie die folgenden Best Practices:
- Verringern 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 Initialisierungsleistung zu verbessern.
- Verwenden Sie serverseitige Rendering (SSR) mit Next.js, um die App-Ladezeit und die Suchmaschinenoptimierung (SEO) zu verbessern.
- Nutzen Sie die in Capacitor integrierten Optimierungen, wie z.B. das Caching des Web-Views und die App-Bündelung.
Zusammenfassung
Sie haben erfolgreich Ihre bestehende Next.js Webanwendung 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:
- Konfiguriert Next.js für statischen Export
- Hinzugefügt Capacitor 8 mit wichtigen Plugins
- Erstellt und bereitgestellt auf iOS- und Android-Emulatoren
- Live-Reload in Entwicklung aktiviert
- Gemeinsame iOS-Bereichsprobleme (viewport, sichere Bereich, Überlauf) behoben
- Hinzugefügt: natürliche Benutzeroberfläche mit Capgo nativer Navigation und Übergängen
Nächste Schritte:
- Einrichten Capgo für über das Internet erfolgende Updates ohne Wiederabgabe bei der App-Stores
- Mehr native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzufügen
- App-Ikone und Splash-Screens für die Produktion einrichten
- Ihre App auf die Einreichung bei App Store und Google Play vorbereiten
Ein neues Projekt starten? Überprüfen Sie Ein Next.js-Mobilanwendung von Grund auf erstellen für eine geführte Einführung.
Ressourcen
- Next.js Dokumentation
- @capgo/capacitor-native-navigation — Liquid Glass Tab-Leiste und natives Chrome
- Capacitor 8 Dokumentation
- @capgo/capacitor-transitions — native-fühlende Seitenübergänge
- @capgo/tailwind-capacitor — Tailwind-Sicherheitsbereichs-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 bauen. sich für ein kostenloses Konto anmelden heute.
Weitermachen von Convert Your Next.js App zu iOS & Android mit Capacitor 8
Wenn Sie Convert Your Next.js App zu iOS & Android mit Capacitor 8 zur Planung von native Plugin-Arbeiten, 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, Ionics Enterprise-Plugin-Alternativen Für den Produktworkflow in Ionics Enterprise-Plugin-Alternativen und Capgo Native Builds Für den Produktworkflow in Capgo Native Builds.
