Einführung
Haben Sie eine bestehende 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 verbessertem Leistung und neuen Funktionen.
Capacitor umhüllt Ihre Web-App in einem nativen Container, der Ihnen Zugriff auf Geräte- APIs wie Kamera, Dateisystem und Push-Benachrichtigungen gibt, 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 statischen Export
- Fügen Sie Capacitor 8 mit wesentlichen 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, Safe Area, horizontale Überlauf)
- Fügen Sie natürliche Anzeige mit Capgo Native Navigation und Transitions hinzu
Sind Sie an der Erstellung eines neuen Projekts von Grund auf interessiert? Überprüfen Sie unsere Anleitung zu Die Erstellung einer mobilen Next.js-Anwendung von Grund auf.
Vorteile der Verwendung von Next.js und Capacitor
- Code Reusability: Next.js ermöglicht es Ihnen, wiederholbar verwendbare Komponenten zu schreiben 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. Server-Seiten-Rendern und code-Splitting, um schnelle Ladezeiten und eine glatte Benutzererfahrung sicherzustellen.
- Native Funktionen: Capacitor bietet Zugriff auf native Gerätefunktionen wie Kamera, Geolocation und mehr, sodass Sie feature-reiche Mobilanwendungen erstellen können.
- Einfache Entwicklung: Mit Capacitor können Sie Ihre Mobilanwendung mit bekannten Webtechnologien entwickeln und testen, wodurch die Lernkurve reduziert und der Entwicklungsprozess gestreamt 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)
Konfigurieren Sie Ihre 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.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' 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 mobilen spezifischen 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 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 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@__CAPGO_KEEP_0__/keyboard
- @capacitor/splash-screen@__CAPGO_KEEP_0__/preferences
- Initialisiere capacitor mit deinen Projekt-Daten:Ersetze
- @capacitor/preferencesErsetze
- Initialize Capacitor with your project details:
bunx cap init my-app com.example.myapp --web-dir outErsetze my-app durch den Namen deiner App 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 Ordner für native Plattformen hinzu:
bunx cap add ios
bunx cap add androidCapacitor wird Ordner erstellen ios und android Ordner am Root Ihres Projekts, 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.
- 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 nativen Plattformen synchronisiert.
Erstellung und Bereitstellung von nativen Apps
Um Ihre native mobile App zu erstellen und zu verteilen, 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 benötigen 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 anzumelden. Öffnen Sie die nativen Projekte: Für iOS: Für Android: Oder direkt mit __CAPGO_KEEP_0__ __CAPGO_KEEP_1__:
- Xcode
Android Studio
bun run mobile:iosApple Developer Program
bun run mobile:androidOr directly with Capacitor CLI:
bunx cap open ios
bunx cap open android- Die App erstellen und ausführen:
-
In Android Studio wartet man auf das Projekt, und klickt dann auf den "Ausführen"-Button, um die App auf einem verbundenen Gerät oder Emulator zu deployen.
-
In Xcode stellt man sein Signierungskonto ein, um die App auf einem echten Gerät zu deployen. Wenn man das noch nicht gemacht hat, wird Xcode einen durchgeführten Prozess anbieten (wobei man sich im Apple Developer Programm angemeldet haben muss). Sobald man das eingerichtet hat, klickt man auf den "Play"-Button, um die App auf dem verbundenen Gerät auszuführen.
Herzlichen Glückwunsch! Sie haben erfolgreich Ihre Next.js Web-App 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:
-
Auf macOS führen Sie den folgenden Befehl im Terminal aus:
ipconfig getifaddr en0 -
Auf Windows ausführen:
ipconfigSuchen Sie die IPv4-Adresse in der Ausgabe.
- Aktualisieren Sie Ihre
capacitor.config.tsum 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 native Projekt:
bunx cap copyDie copy -Anweisung kopiert das Web-Ordner und die Konfigurationsänderungen in das native Projekt ohne das gesamte Projekt zu aktualisieren.
- Rebuild und das App auf Ihrem Gerät mit Android Studio oder Xcode ausführen.
Jetzt werden die Änderungen an Ihrer Next.js App automatisch neu geladen, sobald Sie Änderungen vornehmen, um diese in der mobilen App anzuzeigen.
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-Erweiterungen arbeiten
Capacitor-Erweiterungen ermöglichen Ihnen, Zugriff auf native Gerätefunktionen von Ihrem Next.js-Anwendungsprojekt zu erhalten. Lassen Sie uns herausfinden, wie man die Teilen-Erweiterung als Beispiel verwendet:
- Installieren Sie die Teilen-Erweiterung:
bun add @capacitor/share- Aktualisieren Sie das
pages/index.jsDatei, um die Teilen-Erweiterung 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 Erweiterungen eine Synchronisierungsoperation durchführen und dann die Anwendung auf unserem Gerät neu bereitstellen. Um dies zu tun, führen Sie den folgenden Befehl aus:
bun run mobileOder synchronisieren Sie ohne Neubau:
bunx cap sync- Die Anwendung auf Ihrem Gerät neu bereitstellen.
Jetzt, wenn Sie auf den Button „Jetzt teilen!“ klicken, erscheint das native Teilen-Dialogfeld, wodurch Sie den Inhalt mit anderen Apps teilen können.
Ich habe in den letzten Jahren mit Ionic gearbeitet, um cross-plattformische Anwendungen zu erstellen, aber die Integration mit Next.js ist hackig und selten wertvoll, wenn Sie bereits Tailwind CSS 4.
For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- Für einen nativen mobilen Look in einer Next.js + capgo-Anwendung verwenden Sie capacitor-Plugins anstelle von web-only 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ückseite-Schleife am WebView-Schicht, ohne Ionic-UI zu übernehmen. Installieren Sie beide:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurieren Sie 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 Liquid Glass-Tasteleiste (iOS verwendet die Systemeigene Rendering; Android verwendet ein verschwommenes WebView-Hintergrundbild):
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' });Verwenden Sie für geroutete Seiten cap-router-outlet, cap-page, und cap-content, und rufen Sie setDirection('forward') oder setDirection('back') oder router.push() . Duplizieren Sie Web-Über- oder Fußzeilen nicht, wenn native Navigation diese Oberflächen besitzt. router.back()Siehe die vollständigen Anleitungen:
Verwenden Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Using @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-*) Händisch. 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 Überschuss)
Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder passen Sie den Viewport-Tag an, reicht das normalerweise nicht aus. Arbeiten Sie durch diese Kontrollen in der Reihenfolge.
Stellen Sie sicher, dass der Viewport-Meta-Tag 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',
};Seiten-Router (pages/): setzen Sie den Viewport-Meta-Tag in pages/_app.tsx, nicht _document.tsx (Next.js mag die Tags nicht so wie erwartet für die Verhaltensweise des Viewport anwenden). _document.tsx Behandeln Sie das iOS-Sicherheitsbereich von einem einzigen Root-Wrapper aus.
Erstellen Sie ein einzelnes App-Shell und fügen Sie dort den Sicherheitsbereichs-Puffer an — nicht in mehreren verschachtelten Komponenten:
Verwenden Sie alle Seiteninhalte 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 Sicherheitsbereichs-Puffer in Kopfzeilen, Modalen und Layout-Wrapper machen die Benutzeroberfläche oft gekürzt oder zu groß aus. .app-shellMit
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorausdrücken. pt-safe pb-safe px-safe Setzen Sie __CAPGO_KEEP_0__ iOS
Set Capacitor iOS contentInset to never erstes
In capacitor.config.tspräferieren Sie native Einstellungen deaktiviert und lassen Sie CSS (oder Native Navigation’s) contentInsetMode: 'css'sich das sichere Bereich besorgen:
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 überlaufende Element
Der übliche Täter ist ein Element, das 100vwverwendet w-screen, Tailwind min-width.
, eine fixe Pixelbreite oder eine große
[...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,
}));In Safari Web Inspector, führen Sie Folgendes aus: w-screen mit w-full wenn möglich. Viele horizontale Überschreitung von Problemen kommen von 100vw / w-screendoppelte sichere Bereich Puffer, oder einem fester Breite Container — nicht von der Viewport Meta-Tag selbst.
Leistungsoptimierung
Um die optimale Leistung Ihres Next.js und Capacitor Apps sicherzustellen, beachten Sie die folgenden besten Praktiken:
- 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 Initial-Lade-Leistung zu verbessern.
- Verwenden Sie serverseitige Rendering (SSR) mit Next.js, um die App-Lade-Geschwindigkeit und die Suchmaschinenoptimierung (SEO) zu verbessern.
- Nutzen Sie Capacitor’s eingebaute Optimierungen, wie z.B. Web View-Caching und App-Bündelung.
Schlussfolgerung
Sie haben erfolgreich Ihre bestehende Next.js Web-Anwendung in native iOS- und Android-Apps umgewandelt, mithilfe von Capacitor 8. Ihre Web-Codebase läuft nun nativ auf mobilen Geräten mit Zugriff auf Geräte-APIs.
Was Sie erreicht haben:
- Konfiguriert Next.js für statische Exporte
- Hinzugefügt Capacitor 8 mit wesentlichen Plugins
- Erstellt und bereitgestellt auf iOS- und Android-Simulator
- Aktiviert Live-Reload für Entwicklung
- Gelöst häufige iOS-Ansichtsprobleme (viewport, sichere Fläche, Überlauf)
- Hinzugefügt native anfühlen UI mit Capgo Native Navigation und Übergänge
Nächste Schritte:
- Einrichten Capgo für über das Internet erfolgende Updates ohne App-Store-Wiederabgabe
- Hinzufügen mehrer nativer 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 App Store und Google Play
Starten Sie ein neues Projekt? Überprüfen Sie Ein Next.js-Mobil-App von Grund auf bauen für eine geführte Anleitung.
Ressourcen
- Next.js-Dokumentation
- @capgo/capacitor-native-navigation — Liquid Glass-Tastenleiste und native Chrome
- Capacitor 8-Dokumentation
- @capgo/capacitor-transitions — native anfühlt sich Seitenübergänge
- @capgo/tailwind-capacitor — Sicherheitsbereiche für Capacitor
- Capgo - Live Updates für Capacitor-Apps
Erhalten Sie Informationen darüber, wie Capgo Ihnen helfen kann, bessere Apps schneller zu erstellen Registrieren Sie sich für ein kostenloses Konto heute.
Weitermachen Sie mit Convert Your Next.js App zu iOS & Android mit Capacitor 8
Wenn Sie native Plugin-Arbeiten planen, verbinden Sie es mit Convert Your Next.js App zu iOS & Android mit Capacitor 8 für den Produktworkflow in __CAPGO_KEEP_0__ Plugin Directory für den Produktworkflow in Capgo Plugin Directory Wenn Sie native Plugin-Arbeiten planen, verbinden Sie es mit Capgo Plugin Directory Plugins durch Capacitor von Capgo für die Implementierungsdetails in Plugins durch Capacitor von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren, Alternativen zu Ionic Enterprise Plugins für den Produktworkflow in Alternativen zu Ionic Enterprise Plugins, und Capgo Native Builds für den Produktworkflow in Capgo Native Builds.
