Introduzione
Hai un'applicazione web Next.js esistente? In questo guide, imparerai a trasformarla in app mobili native iOS e Android utilizzando Capacitor 8 — l'ultima versione con prestazioni migliorata e nuove funzionalità.
Capacitor avvolge la tua app web in un contenitore nativo, fornendoti l'accesso a API come la telecamera, il filesystem e le notifiche push, mantenendo intatta la tua base di codice React. A differenza di React Native, non hai bisogno di ri scrivere nulla — il tuo Next.js code funziona come sempre.
Di cosa imparerai:
- Configura la tua app Next.js esistente per l'esportazione statica
- Aggiungi Capacitor 8 con plugin nativi essenziali
- Costruisci e testa su simulatori iOS e Android
- Abilita il reload live per un sviluppo più veloce
- Risolve i comuni problemi di layout iOS (viewport, area sicura, overflow orizzontale)
- Aggiungi un'interfaccia utente che sembra nativa con Capgo Native Navigation e Transizioni
Cercando di iniziare un nuovo progetto da zero? Controlla la nostra guida su Crea un'app mobile Next.js da zero.
I benefici dell'uso di Next.js e Capacitor
- Code Reutilizzabilità: Next.js ti consente di scrivere componenti riutilizzabili e condividere code tra le tue app web e mobili, risparmiando tempo e sforzo di sviluppo.
- Performance: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
- Native Capabilities: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
- Simplified Development: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.
Prerequisites
: Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- Un'app esistente Next.js 15+ applicazione
- Xcode (per lo sviluppo di iOS, disponibile solo su macOS)
- Android Studio (per lo sviluppo di Android)
Configurare la tua App Next.js per dispositivi mobili
Il primo passo è configurare la tua app Next.js per l'esportazione statica. Capacitor richiede file HTML/JS/CSS statici per poterli bundle nella app nativa.
Apre il tuo next.config.js (o next.config.ts) file e aggiungi la configurazione di esportazione:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;La output: 'export' impostazione che consente a Next.js di generare file HTML statici, e images: { unoptimized: true } salta l'ottimizzazione delle immagini di Next.js che richiede un server.
Importante: 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.
Aggiungi script specifici per dispositivi mobili a 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"
}
}Testa l'esportazione statica eseguendo:
bun run buildDevi vedere un out cartella nella radice del tuo progetto. Questo contiene tutti i file statici che Capacitor compilerà nel tuo app nativo.
Aggiungere Capacitor 8 al tuo Progetto
Per pacchettizzare la tua app Next.js in un contenitore mobile nativo, segui questi passaggi:
- Installa Capacitor core e CLI:
bun add @capacitor/core
bun add -D @capacitor/cli- Installa plugin Capacitor comuni che probabilmente avrai bisogno di:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesQuesti plugin forniscono funzioni essenziali:
- @capacitor/app: Gestisci gli eventi di ciclo di vita dell'applicazione (in primo piano/ in background, URL)
- @capacitor/keyboard: Controlla il comportamento del tastierino su dispositivi mobili
- @capacitor/splash-screen: Gestisci lo schermo di benvenuto nativo
- @capacitor/preferences: Memorizza dati chiave-valore persistentemente
- Inizializza Capacitor con i dettagli del tuo progetto:
bunx cap init my-app com.example.myapp --web-dir outSostituisci my-app con il nome del tuo'applicazione e com.example.myapp con il tuo ID dell'applicazione (notazione di dominio inverso).
- Crea o aggiorna il
capacitor.config.tsfile con la configurazione corretta:
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;- Installa le piattaforme native:
bun add @capacitor/ios @capacitor/android- Aggiungi le cartelle delle piattaforme native:
bunx cap add ios
bunx cap add androidCapacitor creerà ios e android cartelle al livello radice del tuo progetto contenenti i progetti nativi.
Per costruire il progetto Android, hai bisogno di Android Studio. Per iOS, hai bisogno di un Mac con Xcode.
- Costruisci e sincronizza il tuo progetto:
bun run mobileQuesto esegue lo script personalizzato che costruisce il progetto Next.js e sincronizza i file statici con le piattaforme native.
Costruire e Distribuire Applicazioni Nativi
Per costruire e distribuire la tua applicazione mobile nativa, segui questi passaggi: Per sviluppare app iOS, hai bisogno di avere Xcode installato, e per le app Android, hai bisogno di avere Android Studio installato. Inoltre, se hai l'intenzione di distribuire la tua app sul negozio di app, hai bisogno di iscriverti al Apple Developer Program per iOS e al Google Play Console per Android.
- Apre le progetti nativi:
Per iOS:
bun run mobile:iosPer Android:
bun run mobile:androidO direttamente con Capacitor CLI:
bunx cap open ios
bunx cap open android- Costruisci e esegui l'app:
-
In Android Studio, attendi che il progetto sia pronto, e poi clicca sul pulsante "Esegui" per distribuire l'app su un dispositivo connesso o emulatore.
-
In Xcode, configura il tuo account di firma per distribuire l'app su un dispositivo reale. Se non l'hai fatto prima, Xcode ti guiderà attraverso il processo (nota che devi essere iscritto al programma sviluppatore di Apple). Una volta configurato, clicca sul pulsante "Gioca" per eseguire l'app sul tuo dispositivo connesso.
Congratulazioni! Hai concesso con successo il tuo web app Next.js su un dispositivo mobile.
Capacitor Live Reload
Durante lo sviluppo, puoi sfruttare il live reloading per vedere i cambiamenti istantaneamente sul tuo dispositivo mobile. Per abilitare questa funzionalità, segui questi passaggi:
- Cerca il tuo indirizzo IP locale:
-
On macOS, esegui il seguente comando nel terminale:
ipconfig getifaddr en0 -
On Windows, esegui:
ipconfigCerca l'indirizzo IPv4 nell'output.
- Aggiorna il tuo
capacitor.config.tsa puntare al tuo server di sviluppo:
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;Sostituisci YOUR_IP_ADDRESS con l'indirizzo IP locale (ad es., 192.168.1.100).
- Applica le modifiche al tuo progetto nativo:
bunx cap copyLa copy comando copia la cartella web e le modifiche di configurazione nel progetto nativo senza aggiornare l'intero progetto.
- Riavvia e esegui l'app sul tuo dispositivo utilizzando Android Studio o Xcode.
Ora, ogni volta che apporti modifiche al tuo app Next.js, l'app mobile si ricaricherà automaticamente per riflettere quelle modifiche.
Nota: Se installi nuovi plugin o apporti modifiche a file nativi, dovrai riavviare il progetto nativo poiché la ricarica in tempo reale si applica solo alle modifiche web code.
Utilizzare Capacitor Plugin
Il Capacitor plugin consente di accedere alle funzionalità del dispositivo nativo dal tuo'app Next.js. Esploriamo come utilizzare il Plugin di condivisione come esempio:
- Installare il plugin di condivisione:
bun add @capacitor/share- Aggiornare il
pages/index.jsfile per utilizzare il plugin di condivisione:
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>
);
}- Sincronizzare le modifiche con il progetto nativo:
Come menzionato in precedenza, quando si installano nuovi plugin, è necessario eseguire un'operazione di sincronizzazione e poi ri-deployare l'app sul dispositivo. Per farlo, esegui il seguente comando:
bun run mobileO sincronizza senza ricostruire:
bunx cap sync- Ricostruisci e esegui l'app sul tuo dispositivo.
Ora, quando clicchi sul pulsante 'Condividi ora!', apparirà il dialogo di condivisione nativo, consentendo di condividere il contenuto con altre app.
Proseguendo, puoi rendere l'app più nativa su iOS e Android con __CAPGO_KEEP_0__ di navigazione e transizioni, e risolvere i problemi di layout comuni di iOS che causano overflow orizzontale o aree sicure tagliate. ## Interfaccia utente con un aspetto nativo con __CAPGO_KEEP_1__ Navigazione e Transizioni native L'ho lavorato per anni con Ionic.
For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- @capgo/capacitor-native-navigation Per un aspetto mobile nativo in un'app Next.js + __CAPGO_KEEP_0__ utilizza invece i plugin __CAPGO_KEEP_1__ al posto di kit UI web come Konsta UI:
- @capgo/capacitor-native-navigation — barra di navigazione nativa, Liquid Glass bar delle schede su iOS e stile di barra delle schede sfocato su Android. Il tuo router Next.js mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con il modello CSS inset per far rispettare il contenuto web le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Visualizza una barra di tab di vetro liquido (iOS utilizza la rendering di sistema; Android utilizza un sfondo di WebView sfocato):
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}`);
});Aggiungi transizioni di pagina native nel contenitore dell'app:
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });Avvolgi le pagine di routing in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') Prima di lavorare su una nuova funzionalità, crea un problema e discuti: router.push() o router.back(). Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa gestisce quelle superfici.
Vedi le guide complete: Usa @capgo/capacitor-navigazione-nativa E e Utilizzando @capgo/capacitor-transizioni.
Aree sicure con Tailwind
Per le aree sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor Pubblicato su tailwind-capacitor npm safe-areas Fornisce utilità e altri plugin di Tailwind compatibili con Capacitor:
bun add -D tailwind-capacitorIn styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilizzare utilità come pt-safe, pb-safe, e px-safe al posto di diffonderle env(safe-area-inset-*) di mano. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Next.js, apri un PR su GitHub.
I Problemi di Layout iOS (Viewport, Area di Sicurezza e Sovrapposizione Orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o modificare il tag viewport da solo non risolve di solito il problema. Passa attraverso questi controlli in ordine.
Assicurati che il tag meta viewport sia applicato correttamente
Router dell'App (app/: esporta viewport da app/layout.tsx:
import type { Viewport } from 'next';
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
viewportFit: 'cover',
};Router delle Pagine (pages/: inserisci il tag meta viewport in pages/_app.tsx, non _document.tsx Aggiungi etichette di Next.js (potrebbe non applicare le etichette come si aspetta per il comportamento dello schermo). _document.tsx Gestisci area sicura di iOS da un solo wrapper radice.
Crea un unico contenitore dell'applicazione e applica il padding dell'area sicura lì — non in componenti nidificati multipli:
Avvolgi tutto il contenuto della pagina all'interno di
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);
}Duplicare il padding dell'area sicura nei titoli, nei modali e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande. .app-shellCon
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorsu quel singolo contenitore. pt-safe pb-safe px-safe Imposta __CAPGO_KEEP_0__ iOS
Set Capacitor iOS contentInset context: Pagina/area: Pagina di prodotti con aggiornamenti in tempo reale. Ruolo: Etichetta breve dell'interfaccia utente o elemento di navigazione. Chiave del messaggio `live_update_dynamic_label_to` (Aggiorna in tempo reale dinamico per). never Iniziamo
In capacitor.config.ts, preferiamo utilizzare le proprietà native disabilitate e lasciare che CSS (o la navigazione nativa) contentInsetMode: 'css') gestisca l'area sicura:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mischia automaticamente l'inserimento di contenuto di Capacitor con CSS env(safe-area-inset-*) L'aggiunta di padding CSS è una causa comune di doppia interlinea.
Trovare l'elemento che sta effettivamente sovrascrivendo
L'elemento colpevole è spesso un elemento che utilizza 100vw, Tailwind w-screen, una larghezza di pixel fissata, o un valore molto min-width.
In Safari Web Inspector, esegui:
[...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,
}));Sostituisci con Tailwind w-screen con w-full quando possibile. Molti problemi di overflow orizzontale derivano da 100vw / w-screen, duplicazione di padding di area sicura, o da un contenitore di larghezza fissata — non dal tag meta viewport stesso.
Optimizzazione delle Prestazioni
Per garantire prestazioni ottimali per il tuo app Next.js e Capacitor, considera le seguenti best practice:
- Minimizza le dimensioni dell'app rimuovendo le dipendenze e gli asset non utilizzati.
- Optimizza le immagini e altri file multimediali per ridurre i tempi di caricamento.
- Implementa il caricamento lazy per i componenti e le pagine per migliorare le prestazioni di caricamento iniziale.
- Utilizza la rendering server-side (SSR) con Next.js per migliorare la velocità di caricamento dell'app e l'ottimizzazione per i motori di ricerca (SEO).
- Sfrutta le ottimizzazioni integrate di Capacitor, come il caching della vista web e la confezione dell'app.
Conclusione
Hai avuto successo nel convertire la tua applicazione web esistente Next.js in app native iOS e Android utilizzando Capacitor 8. Il tuo codice web ora funziona nativamente su dispositivi mobili con accesso alle API di dispositivo.
Ciò che hai realizzato:
- Configurato Next.js per l'esportazione statica
- Aggiunto Capacitor 8 con plugin essenziali
- Costruito e distribuito su simulatori iOS e Android
- Abilitato il reload live per il development
- Risolto problemi di layout iOS comuni (viewport, area sicura, overflow)
- Aggiunto UI con un aspetto nativo con Capgo Native Navigation e Transizioni
Passaggi successivi:
- Configura Capgo per aggiornamenti senza fili senza la riconferma dell'app store
- Aggiungi più plugin nativi come Camera, Geolocalizzazione o Notifiche Push
- Configura icone dell'app e schermate di avvio per la produzione
- Prepara l'app per la sottomissione a App Store e Google Play
Iniziando un nuovo progetto? Controlla Crea un'app mobile Next.js da zero per una guida passo dopo passo.
Risorse
- Documentazione Next.js
- @capgo/capacitor-navigazione nativa --- Liquid Glass barra di navigazione e chrome nativo
- Capacitor 8 Documentazione
- @capgo/capacitor-transizioni --- transizioni di pagina con un sentimento nativo
- @capgo/tailwind-capacitor — Strumenti di area sicura di Tailwind per Capacitor
- Capgo - Aggiornamenti in tempo reale per le App Capacitor
Impara come Capgo possa aiutarti a creare applicazioni migliori in modo più veloce iscrivi il tuo account gratuito oggi.
Continua da Converti la tua App Next.js in iOS & Android con Capacitor 8
Se stai utilizzando Converti la tua App Next.js in iOS & Android con Capacitor 8 per pianificare il lavoro dei plugin nativi, connettilo con Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin Capacitor Plugin da Capgo per il dettaglio di implementazione in Capacitor Plugin da Capgo Aggiungere o Aggiornare Plugin per il dettaglio di implementazione in Aggiungere o Aggiornare Plugin Sostituti di Plugin Enterprise Ionic per il workflow del prodotto in Sostituti di Plugin Enterprise Ionic, e Capgo Costruzione Nativa per il workflow del prodotto in Capgo Costruzione Nativa.
