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, indem Sie Capacitor 8 — die neueste Version mit verbesserten Leistungen und neuen Funktionen.
Capacitor umhüllt Ihre Webanwendung in eine native Container, sodass Sie Zugriff auf Geräte-APIs wie Kamera, Dateisystem und Push-Benachrichtigungen haben, 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.
Wat werden Sie lernen:
- Konfigurieren Sie Ihre bestehende Next.js-Anwendung für statische Export
- Capacitor 8 mit wesentlichen native Plugins hinzufügen
- Erstellen und testen Sie auf iOS- und Android-Emulatoren
- Live-Reload aktivieren, um die Entwicklung zu beschleunigen
- Verbessern Sie häufige iOS-Anordnungsprobleme (Viewport, sichere Fläche, horizontale Überfluss)
- Fügen Sie eine native anfühlsende Benutzeroberfläche mit Capgo Native Navigation und Transitions hinzu
Suchen Sie nach einem neuen Projekt von Grund auf? Überprüfen Sie unsere Anleitung zu Erstellung einer mobilen Next.js-Anwendung von Grund auf.
Vorteile der Verwendung von Next.js und Capacitor
- Code-Reusability: Next.js ermöglicht Ihnen, wiederholbare Komponenten zu schreiben und code zwischen Ihren Web- und mobilen Anwendungen zu teilen, wodurch Entwicklungszeit und -bemühungen eingespart werden.
- Leistung: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
- : Next.js bietet integrierte Leistungsoptimierungen, wie z.B. Serverseitiges Rendering und __CAPGO_KEEP_0__-Splitting, um schnelle Ladezeiten und eine glatte Benutzererfahrung sicherzustellen.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
- : __CAPGO_KEEP_0__ bietet Zugriff auf native Gerätefeatures wie Kamera, Geolocation und mehr, um featurereiche mobile Anwendungen zu erstellen.: Mit Capacitor können Sie Ihre mobile App mit bekannten Web-Technologien entwickeln und testen, wodurch die Lernkurve reduziert und der Entwicklungsprozess beschleunigt wird.
Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:
- Node.js 18+ installiert
- Ein bestehendes Next.js 15+ Anwendung
- Xcode (für iOS-Entwicklung, nur macOS)
- Android Studio (für Android-Entwicklung)
Konfiguration Ihrer Next.js App für Mobilgeräte
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 (API Routen, Serverkomponenten mit Datenabrufen usw.), müssen Sie diese um Client-Seitige Alternativen oder externe APIs umbauen.
Hinzufügen Sie mobilespezifische Skripte zu Ihrer 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 Verzeichnis am Wurzelort Ihres Projekts sehen. Dies enthält alle statischen Dateien, die __CAPGO_KEEP_0__ in Ihre native App einbinden wird. out Capacitor 8 zu Ihrem Projekt hinzufügen
Adding Capacitor 8 to Your Project
__CAPGO_KEEP_0__-Core und __CAPGO_KEEP_1__ installieren:
- Install Capacitor core and CLI:
bun add @capacitor/core
bun add -D @capacitor/cli- Install common Capacitor plugins you’ll likely need:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferences@__CAPGO_KEEP_0__/app
- @capacitor/app@__CAPGO_KEEP_0__/keyboard
- @capacitor/keyboard@__CAPGO_KEEP_0__/splash-screen
- capacitor-Core und __CAPGO_KEEP_1__ installieren: ist not translated as it is a protected token. : Verwalten Sie die native Splash-Screen
- @capacitor/Einstellungen: Speichern Sie Schlüssel-Wert-Daten persistent
- Initialisieren Sie Capacitor mit Ihren Projekt-Daten:
bunx cap init my-app com.example.myapp --web-dir outErsetzen my-app mit Ihrem App-Namen und com.example.myapp mit Ihrem App-ID (umgekehrte Domänennotation).
- Erstellen oder aktualisieren Sie 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;- Installieren Sie native Plattformen:
bun add @capacitor/ios @capacitor/android- Fügen Sie die native Plattform-Ordner hinzu:
bunx cap add ios
bunx cap add androidCapacitor wird erstellen ios und android Felder im Wurzelverzeichnis Ihres Projekts, die die native Projekte enthalten.
Um das Android-Projekt zu erstellen, benötigen Sie Android Studio. Für iOS benötigen Sie einen Mac mit Xcode.
- Das Projekt bauen und synchronisieren:
bun run mobileDies führt Ihre benutzerdefinierte Skript aus, das das Next.js-Projekt erstellt und die statischen Dateien mit den native Plattformen synchronisiert.
Erstellung und Bereitstellung von nativen Apps
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 zu haben, und für Android-Apps benötigen Sie Android Studio installiert. 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 "Ausführen"-Schaltfläche, um die App auf einem verbundenen Gerät oder einem Emulator zu deployen.
-
In Xcode stellen Sie Ihre Signierungskonto ein, um die App auf einem echten Gerät auszuführen. 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 "Spiel"-Schaltfläche, um die App auf Ihrem verbundenen Gerät auszuführen.
Herzlichen Glückwunsch! Sie haben erfolgreich Ihre Next.js-Web-App 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 Mobilgerä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.
- Passen Sie Ihre
capacitor.config.tszur Ihren Entwicklungsserver zuweisen:
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 native Projekt:
bunx cap copyDie copy Der 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 neu geladen, um diese Änderungen widerzuspiegeln.
Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an native Dateien vornehmen, müssen Sie das native Projekt neu erstellen, da live-Neuladen nur auf Web-code-Änderungen angewendet wird.
Mit Capacitor-Plugins
Capacitor-Plugins ermöglichen Ihnen, Zugriff auf native Gerätefeatures von Ihrer Next.js App zu erhalten. Lassen Sie uns sehen, wie Sie das Teilen-Plugin als Beispiel verwenden:
- Installieren Sie das Teilen-Plugin:
bun add @capacitor/share- Die
pages/index.jsDatei zum Auswählen des Share-Plugins:
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>
);
}- Die Änderungen mit dem native Projekt synchronisieren:
Wenn Sie neue Plugins installieren, müssen Sie eine Synchronisierungsoperation durchführen und das App dann auf Ihrem Gerät neu bereitstellen. Um dies zu tun, führen Sie den folgenden Befehl aus:
bun run mobileOder synchronisieren Sie einfach ohne Neubereitstellung:
bunx cap sync- Die App auf Ihrem Gerät neu bereitstellen.
Jetzt, wenn Sie auf den Button „Jetzt teilen!“ klicken, erscheint das native Teilen-Dialogfeld, sodass Sie den Inhalt mit anderen Apps teilen können.
Jahre lang habe ich mit Ionic gearbeite, um cross-plattformische Anwendungen zu erstellen, aber die Integration mit Next.js ist hackig und selten wertvoll, wenn Sie bereits Tailwind CSS 4.
For einen nativen mobilen Look in einer Next.js + Capacitor App verwenden Sie Capgo-Plugins anstatt web-only UI-Kits wie Konsta UI:
- @capgo/capacitor-native-navigation — nativer Navbar, Liquid Glass-Tasteleiste auf iOS und eine verschwommene Tasteleiste-Style auf Android. Ihr Next.js-Router hält die Routen-Zustände; der Plugin besitzt die native Chrome.
- @capgo/capacitor-transitions — Ionic-Style-Seitenübergänge und iOS-Rück-Edge-Swipe im 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 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-Tasteleiste (iOS verwendet die System-eigene 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' });Umranden Sie die gerouteten Seiten mit cap-router-outlet, cap-pageund cap-contentund rufen Sie setDirection('forward') oder setDirection('back') vorher router.push() oder router.back(). Vermeiden Sie Duplikate von Web-Überschriften oder -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-Übergänge.
Safe Areas mit Tailwind
Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (als tailwind-capacitor On npm). Es bietet safe-areas Unterstützung 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 Unterstützung wie pt-safe, pb-safe, und px-safe anstatt sie manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt – wenn etwas für Ihre Next.js-Konfiguration fehlt, env(safe-area-inset-*) Öffnen Sie ein PR auf __CAPGO_KEEP_0__ open a PR on GitHub.
Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr
oder passen Sie die Viewport-Tags alleine an, um es nicht zu beheben. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird
Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow) ist nicht auf __CAPGO_KEEP_0__
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/setzen Sie das Viewport-Meta-Tag ein pages/_app.tsxnicht _document.tsx (Next.js kann die Tags nicht auf die erwartete Weise für das Verhalten des Viewport anwenden). _document.tsx Verwenden Sie den sicheren Bereich von iOS nur von einem Root-Wrapper aus
Erstellen Sie ein einzelnes App-Shell und fügen Sie dort den sicheren Bereich ein — nicht in mehreren verschachtelten Komponenten:
Umfasst alle Seite-Inhalte innerhalb von
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);
}Es ist üblich, dass sicheres Bereich-Padding in Kopfzeilen, Modalen und Layout-Wrapper wiederholt wird, was oft zu einem gekürzten oder zu großen UI-Bereich führt. .app-shellDuplicated safe-area padding in headers, modals, and layout wrappers often makes the UI look cropped or too large.
With @capgo/tailwind-capacitor, Sie können den gleichen Abstand mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Shell.
Setzen Sie Capacitor iOS contentInset auf never erst
In capacitor.config.ts, bevorzugt native inset disabled und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') den sicheren Bereich übernehmen:
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-*) Padding ist eine häufige Ursache für doppelten Abstand.
Finden Sie das echte überfließende Element
Der übliche Täter ist ein Element, das verwendet 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 w-screen mit w-full wenn möglich. Viele horizontale Überflussprobleme kommen von 100vw / w-screen, dupliziertem sicheren Bereichs-Puffer, oder einem fixbreiten Container — nicht von der Viewport-Meta-Tags selbst.
Leistungsoptimierung
To ensure optimal performance of your Next.js and Capacitor app, consider the following 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 die lazy Loading für Komponenten und Seiten, um die Initialladeleistung zu verbessern.
- Verwenden Sie die Server-Seiten-Rendern (SSR) mit Next.js, um die Ladezeit des Apps und die Suchmaschinenoptimierung (SEO) zu verbessern.
- Nutzen Sie die Capacitor-integrierten Optimierungen, wie z.B. das Caching der Webansicht 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.
Wat haben Sie erreicht:
- Konfiguriert Next.js für statischen Export
- Fügte Capacitor 8 mit wichtigen Plugins hinzu
- Baut und deployte auf iOS- und Android-Simulatoren
- Aktiviert live reload für Entwicklung
- Gelöst häufige iOS-Anzeigeprobleme (viewport, safe area, overflow)
- Added native-feeling UI mit Capgo Native Navigation und Transitions
Hinweis:
- Einstellungen Capgo Für über das Internet erfolgende Updates ohne erneute Einreichung bei der App Store
- Hinzufügen von mehreren native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen
- Konfigurieren Sie App-Ikone und Splash-Screens für die Produktion
- Vorbereiten Sie Ihre App für die Einreichung bei der App Store und Google Play
Erstellen Sie ein neues Projekt? Überprüfen Sie Erstellung einer mobilen App mit Next.js von Grund auf zur Anleitung.
Ressourcen
- Next.js Dokumentation
- @capgo/capacitor-native-navigation — Liquid Glass Tab-Leiste und native Chrome
- Capacitor 8 Documentation
- @capgo/capacitor-transitions — native-fühlende Seiten-Übergänge
- @capgo/tailwind-capacitor — Tailwind safe-area utilities for Capacitor
- Capgo - Live Updates for Capacitor Apps
Learn how Capgo can help you build better apps faster, registrieren Sie sich für ein kostenloses Konto heute.
Fortsetzen 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 um native Plugin-Arbeit zu planen, verbinden Sie es mit Capgo Plugin-Verzeichnis zur Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetail in Hinzufügen oder Aktualisieren von Plugins, Ionic Enterprise Plugin Alternativen zur Produktworkflow in Ionic Enterprise Plugin Alternativen, und Capgo native Builds zur Produktionsablauf in Capgo native Builds.
