Introduzione
Hai già un'applicazione web Next.js? In questo guide, imparerai a trasformarla in app mobili native per 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, dando accesso a API di dispositivo come la fotocamera, il filesystem e le notifiche push, mentre mantiene la tua base di codice React esistente. A differenza di React Native, non hai bisogno di ri-scrittura nulla — il tuo Next.js code funziona così com'è.
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 caricamento in tempo reale per un sviluppo più veloce
- Risolve i problemi di layout iOS comuni (viewport, area sicura, overflow orizzontale)
- Aggiungi un'interfaccia utente che sembra nativa con Capgo Navigazione e Transizioni native
Sei alla ricerca di un nuovo progetto da creare da zero? Consulta la nostra guida su Creare un'app mobile Next.js da zero.
I benefici di utilizzare Next.js e Capacitor
- La reusabilità di Code: Next.js ti consente di scrivere componenti riutilizzabili e condividere code tra le tue app web e mobili, risparmiando tempo e sforzo di sviluppo.
- La prestazione: Next.js offre ottimizzazioni di prestazione integrate, come la rendering server-side e code splitting, garantendo tempi di caricamento veloci e un'esperienza utente liscia.
- Funzionalità native: Capacitor offre accesso alle funzionalità di dispositivo nativo come la camera, la geolocalizzazione e altro, consentendo di creare app mobili ricche di funzionalità.
- Sviluppo Semplificato: Con Capacitor, puoi sviluppare e testare la tua app mobile utilizzando tecnologie web familiari, riducendo la curva di apprendimento e semplificando il processo di sviluppo.
Requisiti Preliminari
Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- Un'applicazione esistente Next.js 15+ Xcode
- (per lo sviluppo di iOS, disponibile solo su macOS) installato
- targetLanguage":"Italian","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["Studio di Android","(per lo sviluppo di Android)","Configurare la tua App Next.js per il Mobile","Il primo passo è configurare la tua app Next.js per l'esportazione statica. __CAPGO_KEEP_0__ richiede file HTML/JS/CSS statici per poterli bundle nella app nativa.","Apri il tuo","(o",") file e aggiungi la configurazione di esportazione:","La","impostazione consente a Next.js di generare file HTML statici, e","salta l'ottimizzazione delle immagini di Next.js che richiede un server.","Importante:","Se stai utilizzando funzionalità che richiedono un server (__CAPGO_KEEP_0__ percorsi, componenti server con fetching dei dati, ecc.), dovrai rifare quelle utilizzando alternative client-side o API esterne."]} texts.0
texts.1
The first step is to configure your Next.js app for static export. Capacitor needs static HTML/JS/CSS files to bundle into the native app.
texts.3 next.config.js texts.4 next.config.tstexts.5
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;texts.6 output: 'export' texts.7 images: { unoptimized: true } texts.8
texts.9 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"
}
}Esegui il test dell'esportazione statica con:
bun run buildDevi vedere un out cartella alla radice del tuo progetto. Questa 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:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/preferencesQuesti plugin forniscono funzionalità essenziali:
- @capacitor/app: Gestisci eventi di ciclo di vita dell'app (in primo piano/ background, URL)
- @capacitor/keyboard: Gestisci il comportamento della tastiera su dispositivi mobili
- @capacitor/schermo di benvenuto: Gestisci lo schermo di benvenuto nativo
- @capacitor/preferenze: Salva dati chiave-valore persistentemente
- Inizia Capacitor con i dettagli del tuo progetto:
bunx cap init my-app com.example.myapp --web-dir outSostituisci my-app con il nome della tua app e com.example.myapp con l'ID dell'app (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 piattaforme native:
bun add @capacitor/ios @capacitor/android- Aggiungi le cartelle della piattaforma nativa:
bunx cap add ios
bunx cap add androidCapacitor creerà ios e android cartelle alla 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.
Costruzione e distribuzione di App mobili native
Per costruire e distribuire la tua app mobile nativa, segui questi passaggi: Per sviluppare app iOS, hai bisogno di Xcode installato e per le app Android, è necessario avere installato. Inoltre, se hai l'intenzione di distribuire la tua app sul negozio di app, è necessario iscriverti al Apple Developer Program per iOS e al Google Play Console per Android. Apri i progetti nativi:
- Per iOS:
Per Android:
bun run mobile:iosO direttamente con __CAPGO_KEEP_0__ __CAPGO_KEEP_1__:
bun run mobile:androidOr directly with Capacitor CLI:
bunx cap open ios
bunx cap open android- android-studio-run
-
xcode-run
-
In Xcode, impostare il proprio account di firma per distribuire l'applicazione su un dispositivo reale. Se non l'hai fatto prima, Xcode ti guiderà attraverso il processo (nota che devi essere iscritto al programma di sviluppo di Apple). Una volta impostato, clicca sul pulsante "Play" per eseguire l'applicazione sul tuo dispositivo connesso.
Congratulazioni! Hai avuto successo nel distribuire la tua app web 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:
- Trova l'indirizzo IP locale:
-
Su macOS, esegui il seguente comando nel terminale:
ipconfig getifaddr en0 -
Su Windows, esegui:
ipconfigCerca l'indirizzo IPv4 nell'output.
- Aggiorna il tuo
capacitor.config.tsper 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 esempio, 192.168.1.100).
- Applica le modifiche al tuo progetto nativo:
bunx cap copyIl 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.
Utilizzo dei Capacitor Plugins
I Capacitor plugin ti consentono di accedere alle funzionalità del dispositivo nativo dal tuo app Next.js. Esploriamo come utilizzare il Condividi plugin come esempio:
- Installa il plugin di condivisione:
bun add @capacitor/share- Aggiorna 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>
);
}- Sincronizza le modifiche con il progetto nativo:
Come menzionato in precedenza, quando si installano nuovi plugin, è necessario eseguire un'operazione di sincronizzazione e poi rideployare l'app sul dispositivo. Per farlo, esegui il seguente comando:
bun run mobileOra, 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, consentendoti di condividere il contenuto con altre app.
Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Next.js è un po' artigianale e raramente vale la pena quando già hai Tailwind CSS 4.
Per un aspetto nativo su dispositivi mobili in un'app Next.js + Capacitor utilizza i plugin Capgo al posto di kit UI web come Konsta UI:
- @capgo/capacitor-navigazione-nativa — barra di navigazione nativa, Liquid Glass bar delle schede su iOS, e uno stile di barra delle schede sfocata su Android. Il tuo router Next.js mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
- @capgo/capacitor-transizioni — transizioni di pagina dello stile Ionic e swipe indietro su iOS nell' layer WebView, senza adottare l'UI di Ionic.
Installa entrambi:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con modalità 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',
},
});Rendi una barra delle schede 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 destinazione nel contenitore dell'app: cap-router-outlet, cap-pageE non duplicare i testi delle intestazioni o dei piedi di pagina quando la navigazione nativa gestisce queste superfici. cap-contentUsa la navigazione nativa o chiamala setDirection('forward') o setDirection('back') prima router.push() o router.back(). Non duplicare intestazioni o piedi di pagina web quando la navigazione nativa gestisce queste superfici.
Vedi le guide complete: Usa @capgo/capacitor-navigazione-nativa e Usa @capgo/capacitor-transizioni.
Aree sicure con Tailwind
Per aree sicure del dispositivo in Tailwind CSS, utilizza @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Fornisce safe-areas utilità e altre Capacitor-compatibili estensioni Tailwind:
bun add -D tailwind-capacitorIn styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilizza utilità come pt-safe, pb-safe, e px-safe al posto di aggiungerle env(safe-area-inset-*) manualmente. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Next.js, apri una PR su GitHub.
Risolvere problemi di layout iOS (Viewport, Area di sicurezza, e sovrapposizione orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere overflow-x: hidden o modificando solo la tag di viewport non risolve il problema. Esegui questi controlli in ordine.
Assicurati che la tag meta di viewport sia applicata correttamente
Router dell'applicazione (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/metti la tag di viewport in pages/_app.tsxnon _document.tsx (Next.js potrebbe non applicare le tag in modo diverso da quello che si aspetta per il comportamento di viewport). _document.tsx Gestisci l'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:
Applica il padding dell'area sicura solo una volta, in un contenitore radice, e non in componenti nidificati multipli.
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);
}Avvolgere tutto il contenuto della pagina all'interno di .app-shellLa duplicazione dello spazio di sicurezza dell'area protetta nei titoli, nei modali e nei wrapper di layout può far sembrare l'interfaccia utente tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi esprimere lo stesso spazio di padding con utilità come pt-safe pb-safe px-safe su quel singolo shell.
Imposta Capacitor iOS contentInset a never primo
In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che il CSS (o la navigazione nativa ') contentInsetMode: 'css'possa gestire l'area sicura:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'out',
ios: {
contentInset: 'never',
},
};Mischia Capacitor’s automatico contenuto di inserimento con CSS env(safe-area-inset-*) l'aggiunta di padding è una causa comune di doppia spaziatura.
Cerca l'elemento che sta veramente sovrascrivendo
L'elemento più comune è un elemento che utilizza 100vw, Tailwind w-screen, una larghezza in pixel fissata, o una larghezza 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,
}));Con Tailwind, sostituisci w-screen con w-full quando possibile. Molti problemi di sovrascrittura orizzontale provengono da 100vw / w-screen, duplicato padding di area sicura, o un contenitore di larghezza fissata — non dal tag meta viewport stesso.
Ottimizzazione delle prestazioni
To assicurare le prestazioni ottimali del tuo app Next.js e Capacitor, considera le seguenti best practice:
- Riduci la dimensione dell'app eliminando 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.
Conclusioni
Hai avuto successo nel convertire la tua app 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 dei dispositivi.
Cosa 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 live reload per il development
- Risolto problemi di layout iOS comuni (viewport, area sicura, overflow)
- Aggiunto un'interfaccia utente con un aspetto nativo con Capgo Navigazione nativa e Transizioni
Passaggi successivi:
- Configura Capgo per aggiornamenti senza app store senza riconvalidazione dell'app
- 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 sottoscrizione di App Store e Google Play
Iniziando un nuovo progetto? Controlla Costruisci un'app mobile Next.js da zero per una guida guidata.
Risorse
- Dal documento di Next.js.
- @capgo/capacitor-navigazione nativa — barra di tab di vetro liquido e chrome nativo
- Capacitor 8 Documentazione
- @capgo/capacitor-transizioni — transizioni di pagina con un sentimento nativo
- @capgo/tailwind-capacitor — utilità di area sicura di Tailwind per Capacitor
- Capgo - Aggiornamenti in tempo reale per le app Capacitor
Scopri come Capgo possa aiutarti a costruire app migliori in modo più veloce. registrati gratuitamente oggi.
Continua con 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 i dettagli di implementazione in Capacitor Plugin da Capgo, Aggiungere o Aggiornare i Plugin per i dettagli di implementazione in Aggiungere o Aggiornare i Plugin, Alternativi per Plugin di Enterprise di Ionic per il flusso di lavoro del prodotto in Alternativi per Plugin di Enterprise di Ionic, e Capgo Costruzioni Native per il flusso di lavoro del prodotto in Capgo Costruzioni Native.
