Introduzione
Hai già un'applicazione web Nuxt? In questo guide, imparerai a trasformarla in applicazioni 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 camera, filesystem e notifiche push, mentre mantiene la tua base di codice Vue esistente. A differenza di Flutter o React Native, non hai bisogno di ricodificare nulla — il tuo Nuxt code funziona come sempre.
Cosa imparerai:
- Configura la tua app Nuxt esistente per la generazione statica
- Aggiungi Capacitor 8 con plugin nativi essenziali
- Costruisci e testa sui simulatori di iOS e Android
- Abilita il reload live per un sviluppo più veloce
- Risolve i problemi di layout comuni di iOS (viewport, area sicura, overflow orizzontale)
- Aggiungi un'interfaccia utente che sembra nativa con Capgo Native Navigation e Transitions
Se sei alla ricerca di un nuovo progetto da zero? Esegui il nostro guida su.
I vantaggi di utilizzare Nuxt e Capacitor
- Code Reusabilità: Condividi i tuoi componenti Vue e logica tra app web e mobili.
- Performance: La generazione statica di Nuxt crea pacchetti ottimizzati perfetti per il mobile.
- Funzionalità native: Accedi alle funzionalità del dispositivo come fotocamera, geolocalizzazione e filesystem attraverso Capacitor plugin.
- Sviluppo semplificato: Utilizza pattern familiari Vue/Nuxt senza dover imparare lo sviluppo nativo.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Node.js 18+ installato
- Un'applicazione esistente Nuxt 4 Xcode
- (solo per lo sviluppo di iOS su macOS) Android Studio
- (solo per lo sviluppo di Android) Configurare la tua App Nuxt per i dispositivi mobili
Il primo passo è configurare la tua app Nuxt per la generazione statica. __CAPGO_KEEP_0__ richiede file HTML/JS/CSS statici per poterli bundle nel'app nativa.
Capacitor
Assicurati che il tuo package.json abbia lo script di generazione:
{
"scripts": {
"dev": "nuxt dev",
"build": "nuxt build",
"generate": "nuxt generate",
"preview": "nuxt preview",
"mobile": "bun run generate && bunx cap sync",
"mobile:ios": "bun run mobile && bunx cap open ios",
"mobile:android": "bun run mobile && bunx cap open android"
}
}Importante: Se stai utilizzando funzionalità server-side (API percorsi, middleware del server, ecc.), dovrai rifare quelle per utilizzare alternative client-side o API esterne.
Testa la generazione statica eseguendo:
bun run generateDovresti vedere un .output/public cartella con i tuoi file statici. Questo è ciò che Capacitor compilerà nel tuo app nativa.
Aggiungere Capacitor 8 al tuo Progetto
Per pacchettizzare la tua app Nuxt 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/status-bar @capacitor/preferencesQuesti plugin forniscono funzionalità essenziali:
- @capacitor/app: Gestisci gli eventi di ciclo di vita dell'applicazione (in primo piano/ in background, link profondi)
- @capacitor/keyboard: Controlla il comportamento del tastierino su dispositivi mobili
- @capacitor/splash-screen: Gestisci lo schermo di benvenuto nativo
- @capacitor/status-bar: Stila la barra dello stato del dispositivo
- @capacitor/preferences: Archiviazione di valori chiave (come localStorage ma nativa)
- Inizializza Capacitor con i dettagli del tuo progetto:
bunx cap init my-app com.example.myapp --web-dir .output/publicSostituisci 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: '.output/public',
plugins: {
SplashScreen: {
launchShowDuration: 2000,
launchAutoHide: true,
androidScaleType: 'CENTER_CROP',
splashFullScreen: true,
splashImmersive: true,
},
Keyboard: {
resize: 'body',
resizeOnFullScreen: true,
},
StatusBar: {
style: 'dark',
},
},
};
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 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 genera la costruzione statica Nuxt e sincronizza i file con le piattaforme native.
Costruire e Distribuire Applicazioni Native
Per costruire e distribuire la tua applicazione mobile nativa, segui questi passaggi:
Per sviluppare app iOS, hai bisogno di Xcode installato, e per app Android, hai bisogno di Android Studio installato. Inoltre, se hai l'intenzione di distribuire la tua app sul negozio di app, hai bisogno di iscriverti al programma di sviluppatore Apple per iOS e al Google Play Console per Android.
- Apri i progetti nativi:
Per iOS:
bun run mobile:iosPer Android:
bun run mobile:androidOra 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 o emulatore collegato.
- In Xcode, configura il tuo account di firma per distribuire l'app su un dispositivo reale. Se non hai fatto questo prima, Xcode ti guiderà attraverso il processo (nota che devi essere iscritto al programma di sviluppo Apple). Una volta configurato, clicca sul pulsante “Gioca” per eseguire l'app sul tuo dispositivo collegato.
Congratulazioni! Hai distribuito con successo la tua app web Nuxt su un dispositivo mobile.
Ma aspetta, c'è anche un modo più veloce per farlo durante lo sviluppo…
Capacitor Live Reload
Durante lo sviluppo, puoi sfruttare il live reload 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: '.output/public',
server: {
url: 'http://YOUR_IP_ADDRESS:3000',
cleartext: true,
},
plugins: {
// ... your plugin config
},
};
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 comando copy copia la cartella web e le modifiche di configurazione nel progetto nativo senza aggiornare l'intero progetto.
- Avvia il tuo server di sviluppo Nuxt e ricostruisci in Xcode/Android Studio:
bun run devOra, ogni volta che apportate modifiche al vostro'app Nuxt, l'app mobile si ricaricherà automaticamente per riflettere quelle modifiche.
Nota: Se installate nuovi plugin o apportate modifiche ai file nativi, dovete ricostruire il progetto nativo poiché la ricarica in tempo reale si applica solo alle modifiche web code.
Utilizzo dei Capacitor Plugin
I Capacitor plugin consentono di accedere alle funzionalità del dispositivo nativo dal vostro'app Nuxt. Esploriamo come utilizzare il Plugin di condivisione come esempio:
- Installate il Plugin di condivisione:
bun add @capacitor/share- Crea o aggiorna una pagina per utilizzare il Plugin di condivisione. In Nuxt 4, le pagine vanno in
app/pages/:
<template>
<div class="p-6">
<h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
<button
@click="shareContent"
class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
>
Share now!
</button>
</div>
</template>
<script setup lang="ts">
import { Share } from '@capacitor/share';
async function shareContent() {
await Share.share({
title: 'Check this out!',
text: 'Built with Nuxt and Capacitor',
url: 'https://capacitorjs.com',
dialogTitle: 'Share with friends',
});
}
</script>- Sincronizza le modifiche con il progetto nativo:
bun run mobileO o 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.
Successivamente, puoi rendere l'app più nativa su iOS e Android con Capgo navigazione e transizioni, e risolvere i problemi di layout iOS comuni che causano overflow orizzontale o aree sicure tagliate.
Interfaccia utente con Capgo Navigazione e Transizioni nativa.
Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Nuxt è un processo hacky e raramente vale la pena quando già hai Tailwind CSS.
Per un aspetto mobile nativo in un'app Nuxt + 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 uno stile di barra delle schede sfocato su Android. Il tuo router Nuxt mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
- @capgo/capacitor-transizioni — transizioni di pagina dello stile Ionic e swipe-back di iOS nell'layer WebView, senza adottare l'interfaccia utente di Ionic.
Installa sia:
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',
},
});Rendi una barra di tab di vetro liquido (iOS utilizza la rendering di proprietà del 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 della tua app:
<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';
initTransitions({ platform: 'auto' });
const router = useRouter();
const outletRef = ref(null);
onMounted(() => {
if (outletRef.value) {
setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
}
});
const openSettings = () => {
setDirection('forward');
router.push('/settings');
};
</script>
<template>
<cap-router-outlet ref="outletRef">
<router-view />
</cap-router-outlet>
</template>Avvolgi le pagine di routing in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima di navigare. Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede queste superfici.
Vedi le guide complete: Utilizza @capgo/capacitor-navigazione-nativa e Utilizzando @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 altri plugin Tailwind compatibili con Capacitor:
bun add -D tailwind-capacitorIn app/assets/css/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Per Nuxt 4 con Tailwind CSS 4, conserva questa importazione nel file CSS richiamato da nuxt.config.ts.
Utilizza utilità come pt-safe, pb-safe, e px-safe al posto di spargere env(safe-area-inset-*) in modo manuale. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Nuxt, apri una PR su GitHub.
Risolvere Problemi di Layout iOS (Viewport, Area di Sicurezza e Flusso Orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o modificare solo la tag di viewport di solito non risolve il problema. Passa attraverso questi controlli in ordine.
Assicurati che la tag meta viewport sia applicata correttamente
In nuxt.config.ts, impostare il viewport tramite app.head:
export default defineNuxtConfig({
app: {
head: {
meta: [
{
name: 'viewport',
content: 'width=device-width, initial-scale=1, viewport-fit=cover',
},
],
},
},
});Gestisci l'area di sicurezza di iOS da un wrapper radice solo
Crea un unico contenitore dell'applicazione e applica il padding dell'area di sicurezza lì — non in più componenti nidificati:
html,
body,
#__nuxt {
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-shell. Il duplicato del padding dell'area di sicurezza nei titoli, nei modali e nei wrapper di layout spesso fa sembrare il UI tagliato o troppo grande.
With @capgo/tailwind-capacitor, puoi esprimere la stessa spaziatura con utility come pt-safe pb-safe px-safe su quella singola shell.
Imposta Capacitor iOS contentInset a never primo
In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che 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 insetto con CSS env(safe-area-inset-*) la spaziatura è una causa comune di doppia spaziatura.
Trova l'elemento che sta effettivamente sovraccaricando
Il solito colpevole è un elemento che utilizza 100vwTailwind w-screen, una larghezza in pixel fisse, o un 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-screenduplicati padding di area sicura, o un contenitore di larghezza fissata — non dal tag meta viewport stesso.
Conclusione
Hai avuto successo nel convertire la tua applicazione web esistente Nuxt in app native iOS e Android utilizzando Capacitor 8. Il tuo codice Vue ora funziona nativamente su dispositivi mobili con accesso a API di dispositivo.
Cosa hai ottenuto:
- Configurato Nuxt per la generazione 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 sentore nativo con Capgo Native Navigation e Transizioni
Passaggi successivi:
- Configurazione Capgo per aggiornamenti senza app store senza riconvalidazione
- Aggiungi plugin nativi come Camera, Geolocalizzazione o Notifiche Push
- Configurazione di icone e schermate di benvenuto per la produzione
- Preparare l'app per la presentazione su App Store e Google Play
Iniziando un nuovo progetto? Consulta Creare un'app Nuxt Mobile da zero per una guida dettagliata.
Risorse
- Documentazione Nuxt
- Capacitor 8 Documentazione
- @capgo/capacitor-navigazione nativa — barra di navigazione Liquido Glass e chrome nativo
- @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 Capacitor Applicazioni
Impari come Capgo possa aiutarti a costruire applicazioni migliori in modo più veloce, iscrivi un account gratuito oggi.
Continua da Converti la tua App Nuxt in iOS & Android con Capacitor 8
Se stai utilizzando Converti la tua App Nuxt 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 nei plugin Capacitor di Capgo, Aggiungere o Aggiornare Plugin per i dettagli di implementazione in Aggiungere o Aggiornare Plugin, Alternative per Plugin Enterprise di Ionic per il workflow del prodotto in Alternative per Plugin Enterprise di Ionic, e Capgo Build Nativo per il workflow del prodotto in Capgo Build Nativo.
