Introduzione
Hai già un'app web Next.js? In questo tutorial, 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, fornendoti accesso a API di dispositivo come camera, filesystem e notifiche push, mentre mantiene il tuo codice React esistente. A differenza di React Native, non devi ri-scrittura nulla — la tua app Next.js code funziona comunque.
Ciò che 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 in tempo reale per un sviluppo più veloce
- Risolve i problemi di layout iOS comuni (viewport, area sicura, overflow orizzontale)
- Aggiungi un'interfaccia utente con un aspetto nativo con Capgo Navigazione e Transizioni native
Desideri iniziare un nuovo progetto da zero? Consulta la nostra guida su Costruire un'app mobile Next.js da zero.
I benefici dell'utilizzo 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.
- PerformanceNext.js offre ottimizzazioni di prestazioni integrate, come la rendering server-side e lo splitting code, garantendo tempi di caricamento veloci e un'esperienza utente fluida.
- Capacità native: Capacitor offre accesso a funzionalità di dispositivo nativo come la fotocamera, 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.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- An existing Next.js 15+ Xcode
- Xcode (per iOS sviluppo, disponibile solo su macOS)
- Sviluppo Semplificato (per lo sviluppo di Android)
Configurazione dell'app Next.js per dispositivi mobili
Il primo passo è configurare l'app Next.js per l'esportazione statica. Capacitor richiede file HTML/JS/CSS statici per poterli bundle nell'app nativa.
Apri il tuo next.config.js o next.config.tsfile e aggiungi la configurazione di esportazione:
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;Il output: 'export' impostazione 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: Se stai utilizzando funzionalità che richiedono un server (API percorsi, componenti server con fetching dei dati, ecc.), dovrai rifare quelle utilizzando alternative client-side o API esterne.
Aggiungi script specifici per dispositivi mobili 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"
}
}Testare l'esportazione statica eseguendo:
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/tastiera: Controlla il comportamento della tastiera su mobile
- @capacitor/schermo di avvio: Gestisci lo schermo di avvio nativo
- @capacitor/preferenze: Salva 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 della tua app e com.example.myapp con l'ID della tua 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 delle piattaforme native:
bunx cap add ios
bunx cap add androidCapacitor creerà ios e android i cartelle nella 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 il tuo script personalizzato che costruisce il progetto Next.js e sincronizza i file statici con le piattaforme native.
Costruire e Distribuire Applicazioni 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 Android Studio installato. Inoltre, se hai l'intenzione di distribuire la tua app sul negozio di app, devi iscriverti al programma di sviluppatore Apple 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 di sviluppatore Apple). Una volta configurato, clicca sul pulsante "Gioca" per eseguire l'app sul tuo dispositivo connesso.
Ecco! Hai avuto successo nel distribuire la tua app web Next.js su un dispositivo mobile.
Capacitor Ricostruzione in tempo reale
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:
-
Sul macOS, esegui il seguente comando nel terminale:
ipconfig getifaddr en0 -
Sul 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 il tuo indirizzo IP locale (ad es. 192.168.1.100).
- Applica le modifiche al tuo progetto nativo:
bunx cap copyLa copy il comando copia il folder 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.
Note: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.
Utilizzando Plugin Capacitor
Capacitor plugins allow you to access native device features from your Next.js app. Let’s explore how to use the Condividi plugin plugin di condivisione
- Installa 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 i cambiamenti 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.
L'ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Next.js è un po' hacky e raramente vale la pena quando già hai Tailwind CSS 4.
Per un'esperienza di mobile nativo in un'app Next.js + Capacitor, utilizza i plugin Capgo al posto di kit UI web-only come Konsta UI:
- @capgo/capacitor-navigazione nativa — barra di navigazione nativa, Liquid Glass bar delle schede su iOS e stile di barra delle schede sfocata su Android. Il 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 nel 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',
},
});Visualizza una barra dei tab di vetro liquido (iOS utilizza la rendering di sistema; Android utilizza un sfondo 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 le 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 in cap-router-outlet, cap-pagee cap-contente e call setDirection('forward') o setDirection('back') before router.push() o router.back()Non duplicare intestazioni o piè di pagina web quando la navigazione nativa gestisce queste superfici.
Ecco alcune alternative, e chiama Usando @capgo/capacitor-navigazione nativa and Usando @capgo/capacitor-transizioni.
Ecco alcune alternative, e chiama
Ecco alcune alternative, e chiama @capgo/tailwind-capacitor (pubblicato come) tailwind-capacitor su npm). Offre safe-areas 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";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 un 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 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/da viewport from 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 per la viewport pages/_app.tsx, not _document.tsx Gestisci l'area sicura di iOS da un solo wrapper radice _document.tsx il modo in cui si comporta la viewport (come si aspetta).
Avvolgi tutta il contenuto della pagina dentro
Crea un unico contenitore dell'applicazione e applica il padding di area sicura lì — 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);
}Avvolgi tutto il contenuto della pagina all'interno .app-shellLa duplicazione dello spazio di sicurezza nelle intestazioni, nei modali e nei wrapper di layout può rendere 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 su never primo
In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che il 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',
},
};Mescolare Capacitor's automatico contenuto insetto con CSS env(safe-area-inset-*) La spaziatura è una causa comune di doppia spaziatura.
Trova l'elemento sovrapposto reale
Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screenuna larghezza fisso di pixel, o una grande 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 sovraccarico orizzontale derivano da 100vw / w-screen, padding di area sicura duplicato, o un contenitore a 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:
- Riduci la dimensione dell'applicazione 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 componenti e 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 creazione di bundle dell'applicazione.
Conclusioni
Hai avuto successo nel convertire la tua applicazione web esistente Next.js in applicazioni 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 ottenuto:
- Configurato Next.js per l'esportazione statica
- Aggiunto Capacitor 8 con plugin essenziali
- Costruito e distribuito su simulatori iOS e Android
- Abilitato il caricamento live per lo sviluppo
- Risolto problemi di layout iOS comuni (viewport, area sicura, overflow)
- Aggiunto UI con un sentimento nativo con Capgo Navigazione e Transizioni native
Next steps:
- Configura Capgo per aggiornamenti in rete senza la riconferma dell'app store
- Aggiungi più plugin nativi come Camera, Geolocalizzazione o Notifiche Push
- Configura icone e schermate di avvio per la produzione
- Prepara l'app per la sottoscrizione di App Store e Google Play
Inizia un nuovo progetto? Consulta Costruisci un'app mobile Next.js da zero per una guida passo dopo passo.
Risorse
- Documentazione di Next.js
- @capgo/capacitor-navigazione nativa — Barra di navigazione 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 - Live Updates for Capacitor Apps
Learn how Capgo can help you build better apps faster, iscrivi un account gratuito oggi.
Continua con Converti il tuo'app Next.js in iOS & Android con Capacitor 8
Se stai utilizzando Converti il tuo'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 Sostituti dei Plugin Enterprise di Ionic per il flusso di lavoro del prodotto in Alternative Plugin Enterprise Ionic Capgo Costruzione Nativa per il flusso di lavoro del prodotto in Capgo Costruzione Nativa.
