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 __CAPGO_KEEP_0__ verwenden Capacitor 8 — die neueste Version mit verbesserten Leistungen 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 – Ihr Next.js code läuft unverändert weiter.
Was Sie lernen werden:
- Konfigurieren Sie Ihre bestehende Next.js-Anwendung für statische Exportierung
- Fügen Sie Capacitor 8 mit wichtigen nativen Plugins hinzu
- Erstellen und testen Sie auf iOS- und Android-Emulatoren
- Aktivieren Sie Live-Reload für eine schnellere Entwicklung
- Lösen Sie häufige iOS-Ansichtsprobleme (viewport, sichere Bereich, horizontale Überlauf)
- Fügen Sie natürliche Anzeigen mit Capgo Native Navigation und Transitions hinzu
Planen Sie ein neues Projekt von Grund auf? Überprüfen Sie unsere Anleitung zu Building a Next.js Mobile App from Scratch.
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 Mobilanwendungen 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 Server-Seiten-Rendern 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ätefunktionen wie die Kamera, die Geolocation und vieles mehr, um Ihnen die Möglichkeit zu geben, feature-reiche Mobilanwendungen zu erstellen.: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.
: Mit __CAPGO_KEEP_0__ können Sie Ihre Mobilanwendung mit bekannten Web-Technologien entwickeln und testen, wodurch die Lernkurve reduziert und der Entwicklungsprozess gestreamlinert wird.
Voraussetzungen
- : Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben: Node.js 18+
- installiert sind, Next.js 15+ Anwendung
- Xcode (für die iOS-Entwicklung, nur macOS)
- Android Studio (für die 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 bündeln.
Öffnen Sie Ihr next.config.js (oder next.config.ts)
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;Datei und fügen Sie die Export-Konfiguration hinzu: output: 'export' Die Einstellung erzählt Next.js, statische HTML-Dateien zu generieren, und images: { unoptimized: true } umgeht die 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 Sie mobilespezifische Skripte 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"
}
}Testen Sie die statische Ausgabe, indem Sie Folgendes ausführen:
bun run buildSie sollten ein out Ordner am Wurzelverzeichnis Ihres Projekts sehen. Dieser enthält alle statischen Dateien, die Capacitor in Ihre native App einbinden wird.
Capacitor 8 in 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 die gängigen Capacitor-Plugins, die Sie benötigen:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesDiese Plugins liefern wichtige Funktionen:
- @capacitor/app: App-Lebenszyklusereignisse (Vordergrund/Hintergrund, URLs) verwalten
- @capacitor/keyboard: Tastaturverhalten auf Mobilgeräten steuern
- @capacitor/splash-screen: Die native Splash-Screen verwalten
- @capacitor/preferences: Schlüssel-Wert-Daten persistent speichern
- Initialisieren Sie Capacitor mit Ihren Projekt-Details:
bunx cap init my-app com.example.myapp --web-dir outErsetzen my-app mit Ihrem App-Namen und com.example.myapp mit Ihrer 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 Plattformordner hinzu:
bunx cap add ios
bunx cap add androidCapacitor wird die ios und android Ordner am Root Ihres Projekts enthalten, die die native Projekte aufweisen.
Um das Android-Projekt zu bauen, benötigen Sie Android StudioFür iOS benötigen Sie einen Mac mit Xcode.
- Projekt erstellen und synchronisieren:
bun run mobileDies 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 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 zu haben. Darüber hinaus müssen Sie, wenn Sie Ihre App im App Store verteilen möchten, sich bei Apple Developer Program für iOS und Google Play Console für Android anmelden. Öffnen Sie die native Projekte: Für iOS: Für Android:
- Oder direkt mit __CAPGO_KEEP_0__ __CAPGO_KEEP_1__:
Erstellung und Bereitstellung von nativen Apps
bun run mobile:iosUm Ihre native mobile App zu erstellen und zu bereitstellen, folgen Sie bitte diesen Schritten:
bun run mobile:androidOr directly with Capacitor CLI:
bunx cap open ios
bunx cap open android- Entwickeln und ausführen Sie die App:
-
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 Signierungskonto ein, um die App auf einem echten Gerät zu deployen. Wenn Sie dies noch nicht getan haben, wird Xcode Ihnen durch den Prozess führen (beachten Sie, dass Sie sich im Apple Developer Programm angemeldet haben müssen). Sobald Sie eingerichtet sind, klicken Sie auf die Schaltfläche "Spiel" zum Ausführen der App auf Ihrem verbundenen Gerät.
Glückwunsch! Sie haben Ihre Next.js-Web-App erfolgreich auf einem mobilen Gerät deployt.
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:
-
On macOS führen Sie den folgenden Befehl in der Terminal-Anwendung aus:
ipconfig getifaddr en0 -
On Windows, führen Sie folgendes Kommando aus:
ipconfigSuchen Sie nach der IPv4-Adresse in der Ausgabe.
- Update Ihrer
capacitor.config.tszum Punkt Ihres Entwicklungsservers:
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 Befehl kopiert das Web-Verzeichnis und die Konfigurationsänderungen in das native Projekt ohne das Update des gesamten Projekts.
- Rebuild und führen Sie die App auf Ihrem Gerät mit Android Studio oder Xcode aus.
Jetzt werden Ihre Änderungen an der Next.js App automatisch auf die mobile App übertragen, sodass diese sich neu laden wird.
Hinweis: Wenn Sie neue Plugins installieren oder Änderungen an native Dateien vornehmen, müssen Sie das native Projekt neu erstellen, da live-Reload nur auf Web-code-Änderungen angewendet wird.
Mit Capacitor-Plugins verwenden
Capacitor-Plugins ermöglichen Ihnen, Zugriff auf native Gerätefeatures von Ihrem Next.js-Anwendungscode zu erhalten. Lassen Sie uns sehen, wie Sie das Teilen-Plugin als Beispiel verwenden:
- Installieren Sie das Teilen-Plugin:
bun add @capacitor/share- Ändern Sie das
pages/index.jsDatei, um das Teilen-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 mobileOder 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.
## Eine natürliche Benutzeroberfläche mit __CAPGO_KEEP_1__-Native-Navigation und -Übergängen Ich habe Jahre lang mit Ionic gearbeite, um cross-plattformische Anwendungen zu erstellen, aber die Integration mit Next.js ist hackig und selten wertvoll, wenn du bereits .
For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- besitzt. Für eine natürliche mobile App in einer Next.js + capgo-Anwendung verwende stattdessen capacitor-Plugins anstelle von web-basierten UI-Kits wie Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
- @capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
— Ionic-Style-Seiteneinblendungen und iOS-Rückblende durch Wischen am WebView-Schicht, ohne Ionic-Benutzeroberfläche zu übernehmen. Installiere beide:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurieren 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 einen Liquid Glass-Tasteleisten (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' });Wrap routed Pages in cap-router-outlet, cap-page, und cap-content, und rufen Sie setDirection('forward') oder setDirection('back') Bevor Sie an einem neuen Feature arbeiten, erstellen Sie ein Issue und diskutieren Sie es. router.push() oder router.back(). Duplizieren Sie Web-Überschriften oder -Fußzeilen nicht, wenn native Navigation diese Oberflächen besitzt.
Siehe die vollständigen Anleitungen: Verwenden Sie @capgo/capacitor-native-navigation und Mit @capgo/capacitor-Übergängen.
Sichere Bereiche mit Tailwind
Für sichere Bereiche auf Geräten in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (als tailwind-capacitor auf npm). Es bietet safe-areas Nützliche Funktionen 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ützliche Funktionen wie pt-safe, pb-safe, und px-safe anstatt sie zu verteilen env(safe-area-inset-*) per Hand. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Next.js-Einrichtung 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, hilft das Hinzufügen oder Anpassen des Viewport-Tags normalerweise nicht. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird
App Router
exportieren Sie (app/von viewport Pages Router app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};legen Sie den Viewport-Meta-Tag in (pages/, nicht pages/_app.tsx, not _document.tsx (Next.js mag die Tags nicht wie erwartet für die Ansichtsverhalten anwenden). _document.tsx Behandeln Sie das iOS-Sicherheitsbereich von einem einzigen Root-Wrapper aus.
Erstellen Sie eine einzelne App-Shell und fügen Sie dort den Sicherheitsbereich-Puffer an – nicht in mehreren verschachtelten Komponenten:
Verwenden Sie 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);
}Doppelte Sicherheitsbereich-Puffer in Kopfzeilen, Modalen und Layout-Wrapper machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen. .app-shellMit
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorauf dieser einzigen Schale ausdrücken. pt-safe pb-safe px-safe Setzen Sie __CAPGO_KEEP_0__ iOS
Set Capacitor iOS contentInset Ziel: Kurze Benutzeroberflächenelemente oder Navigationsitems. Nachrichtsschlüssel `live_update_dynamic_label_to` (Live Update Dynamic Label To). never erste
In capacitor.config.ts, bevor Sie native Einstellungen deaktivieren und CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Bereiche übernehmen:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mischen Sie Capacitor’s automatische Inhalts-Einstellungen 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 Pixel-Breite 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 sicheres 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:
- Klein halten 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-Ladeleistung zu verbessern.
- Verwenden Sie serverseitige Rendering (SSR) mit Next.js, um die Ladezeit und die Suchmaschinenoptimierung (SEO) der App zu verbessern.
- Nutzen Sie die Capacitor-integrierten Optimierungen, wie z.B. das Caching des Web-Views und die App-Bündelung.
Zusammenfassung
Ihr Web-Codebase wurde erfolgreich in native iOS- und Android-Apps umgewandelt, die mit Capacitor 8 erstellt wurden. Ihre Web-Codebase läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräte-APIs.
Was Sie erreicht haben:
- Konfigurierte Next.js für statische Exporte
- Fügte Capacitor 8 mit wichtigen Plugins hinzu
- Baut und deployte auf iOS- und Android-Emulatoren
- Aktivierte Live-Reload für Entwicklung
- Löste häufige iOS-Ansichten (viewport, sichere Fläche, Überlauf) aus
- Fügte eine native anfühlsende Benutzeroberfläche mit Capgo Native Navigation und Transitions hinzu
Nächste Schritte:
- Einstellungen Capgo für über-ein-Netz-Updates ohne App-Store-Wiederabgabe
- Fügen Sie mehr native Plugins wie Kamera, Geolocation oder Push-Benachrichtigungen hinzu
- Konfiguration von App-Ikonen und Splash-Screens für die Produktion
- Vorbereiten Sie Ihre App für die Einreichung bei App Store und Google Play
Neuanfang? Überprüfen Sie Erstellung einer mobilen App mit Next.js von Grund auf um eine Schritt-für-Schritt-Anleitung zu erhalten.
Ressourcen
- Next.js-Dokumentation
- @capgo/capacitor-native-Navigation — Liquid Glass-Tastenleiste und native Chrome
- Capacitor 8-Dokumentation
- @capgo/capacitor-Übergänge — native-fühlende Seitenübergänge
- @capgo/tailwind-capacitor — Tailwind-Unterstützung für sichere Bereiche von Capacitor
- Capgo - Live-Updates für Capacitor-Apps
Erfahren Sie, wie Capgo Ihnen helfen kann, bessere Apps schneller zu erstellen sich für ein kostenloses Konto anmelden heute
Fahren Sie mit dem Konvertieren Ihres Next.js-Apps in iOS- und Android-Apps mit Capacitor 8 fort
Wenn Sie Fahren Sie mit dem Konvertieren Ihres Next.js-Apps in iOS- und Android-Apps mit Capacitor 8 fort zur Planung von native Plug-in-Arbeiten verwenden, verbinden Sie es mit Capgo-Plugin-Verzeichnis für den 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 Alternativen zu Ionic Enterprise Plugins zum Produktworkflow in Alternativen zu Ionic Enterprise Plugins, und Capgo Native Builds zum Produktworkflow in Capgo Native Builds.
