Spostare Next.js da Vercel: guida alla migrazione

Puoi spostare un’applicazione Next.js da Vercel senza cambiare framework. Next.js funziona su hosting compatibili con Node.js. Il lavoro consiste nel far funzionare impostazioni, servizi collegati e attività programmate nel nuovo ambiente. Next.js: opzioni di distribuzione

La prima migrazione è in genere più semplice se mantieni la base di dati e l’archiviazione dei file, fai funzionare l’applicazione a un nuovo URL e poi sposti il dominio. Avrai meno problemi da analizzare contemporaneamente.

Questa guida segue quel processo. Puoi usarla con l’hosting Node.js che preferisci; gli esempi Adios mostrano un modo di applicare i passaggi. Ti serviranno i file del progetto, l’accesso alle impostazioni Vercel e, al momento del cambio, alle impostazioni DNS del dominio.

1. Prepara un breve elenco dei servizi usati dall’applicazione

Mantieni i servizi che già funzionano

Spostare l’applicazione non significa necessariamente spostare i dati. Se la base di dati accetta connessioni dal nuovo hosting, di solito puoi mantenerla. Controlla se esiste un elenco di IP consentiti o altre restrizioni di connessione.

Fai lo stesso per l’archiviazione dei file, l’autenticazione, i pagamenti e l’e-mail. Mantieni i servizi con cui ti trovi bene se supportano la nuova configurazione. Per esempio, Vercel documenta l’accesso a Blob dall’esterno di Vercel con un token di lettura e scrittura. Autenticazione Vercel Blob

Salva una versione funzionante del codice prima di iniziare. Per questo primo trasferimento, evita di abbinare il cambio di hosting a un aggiornamento del framework o a una riprogettazione della base di dati.

Controlla le impostazioni attualmente fornite da Vercel

Apri le impostazioni del progetto Vercel e i file del tuo progetto package.json, next.config.*, e vercel.json, se presente. Compila questa breve lista:

Cosa cercare	Cosa annotare
Impostazioni di compilazione	Versione di Node, gestore dei pacchetti, comando di compilazione e cartella del progetto
Variabili d’ambiente	Nomi delle variabili e appartenenza a Production, Preview o Development
Base di dati e archiviazione	Quali servizi usi e se il nuovo hosting può collegarsi
Accesso e pagamenti	URL di callback e di webhook che puntano all’applicazione attuale
Attività cron	Quale URL chiama ogni attività, con quale frequenza e cosa modifica
Domini	Quale dominio usano i visitatori e dove viene gestito il DNS

Un URL di callback è l’indirizzo a cui un servizio rimanda l’utente dopo un’operazione, come l’accesso. Un URL di webhook riceve una notifica da un altro servizio, ad esempio un aggiornamento di pagamento. Potrebbe essere necessario modificare entrambi quando cambia l’indirizzo dell’applicazione.

Cerca inoltre nel codice @vercel/ e VERCEL_. Esamina ogni risultato: alcune integrazioni funzionano anche altrove, mentre altre dipendono da un valore o un servizio fornito da Vercel. Il nuovo hosting non ricreerà automaticamente quelle impostazioni.

Mantieni disponibile il deploy precedente mentre prepari e testi quello nuovo.

2. Verifica che l’applicazione funzioni in modalità produzione

Compila e avvia l’applicazione sul tuo computer

Parti dalla versione di Node e dal gestore dei pacchetti già usati dal progetto. Questi esempi usano npm e presuppongono che tu abbia nel repository un file package-lock.json.

Verifica che gli script in package.json includano queste voci. Integrale con gli script esistenti e conserva i passaggi di compilazione necessari all’applicazione.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

In un terminale aperto nella cartella dell’applicazione, esegui:

npm ci --include=dev
npm run build
npm start

npm ci installa le versioni salvate nel lockfile. npm run build prepara l’applicazione per la produzione. npm start esegue quella compilazione. Se usi pnpm o Yarn, utilizza i comandi equivalenti del progetto. Configurare Next.js come server Node

Apri l’indirizzo locale mostrato nel terminale. Controlla alcune pagine, inclusa una che carica dati. Se la compilazione segnala un’impostazione mancante, aggiungila all’ambiente locale e riprova. Usa credenziali di test per operazioni che inviano e-mail, addebitano pagamenti o modificano dati dei clienti.

Questo esempio usa la configurazione standard next start. Se l’applicazione usa già output: 'standalone', mantieni il comando di avvio del server generato e includi le risorse per il browser. Le istruzioni standalone di Next.js spiegano questa opzione di packaging.

Facoltativo: descrivi la configurazione per Adios

Nell’hosting scelto, configura il comando di compilazione, quello di avvio e la porta. La porta è il numero su cui l’applicazione resta in ascolto; l’impostazione dell’hosting deve coincidere con quella dell’applicazione.

Per Adios, crea adios.yaml accanto a package.json. Questo esempio usa Node 24, un’istanza in esecuzione e la porta 3000:

name: my-nextjs-app
region: de
replicas: 1

build_cmd: npm ci --include=dev && npm run build
start_cmd: npm start -- --hostname 0.0.0.0 --port 3000

runtime:
  name: node@24
  port: 3000
  health_path: /api/health
  memory_mb: 1024

Scegli una versione di Node supportata e compatibile con l’applicazione e una regione disponibile per il tuo team. L’impostazione --hostname 0.0.0.0 permette all’hosting di raggiungere l’applicazione in esecuzione. Completa le impostazioni nella sezione successiva prima del deploy. La Guida rapida di Adios spiega questi campi.

Il health_path è un URL che l’hosting controlla per verificare che l’applicazione risponda. Se non ne hai già uno, inserisci questo esempio di base per App Router in app/api/health/route.js, oppure src/app/api/health/route.js se usi src/:

export function GET() {
  return Response.json({ status: 'ok' })
}

Verifica che il middleware di autenticazione permetta di accedere a questo URL senza login. Questo controllo conferma che l’applicazione risponde; non dimostra che funzionino accesso, pagamenti o base di dati. Li proverai separatamente.

3. Copia le impostazioni e collega i servizi

Metti ogni impostazione al posto giusto

Copia le impostazioni necessarie da Vercel alla configurazione del nuovo hosting. Usa valori adatti all’ambiente che stai provando: un deploy di test deve usare chiavi di pagamento di test e dati appropriati.

Un’impostazione può essere necessaria in due momenti:

Durante la compilazione: mentre npm run build prepara l’applicazione.
Durante l’esecuzione: mentre l’applicazione compilata serve le richieste.

Esempio di impostazione	Dove va di solito
`NEXT_PUBLIC_SITE_URL`	Impostazioni di compilazione; il valore può comparire nel browser
`DATABASE_URL`	Impostazioni private del server; anche di compilazione se questa legge la base di dati
Segreto di firma per l’autenticazione	Impostazioni private del server, secondo le istruzioni della libreria di autenticazione
Chiave API di pagamento o e-mail	Impostazioni private del server
`CRON_SECRET`	Impostazioni private del server per l’esempio di attività programmata seguente

Usa i nomi reali delle variabili della tua applicazione. Un nome che inizia con NEXT_PUBLIC_ indica informazioni che possono essere pubbliche. Non usare mai quel prefisso per una password o una chiave API privata.

Next.js inserisce i valori NEXT_PUBLIC_* richiamati direttamente nel codice del browser durante la compilazione. Se ne modifichi uno, ricompila l’applicazione. Cambiare solo un’impostazione di esecuzione non aggiorna quel codice del browser. Next.js: variabili d’ambiente

Facoltativo: aggiungi i segreti Adios ed esegui il deploy

In Adios, seleziona il team proprietario dell’applicazione e crea i valori privati in Segreti. Poi fai riferimento a questi valori in adios.yaml. Per un’applicazione che usa queste due variabili, aggiungi:

env:
  DATABASE_URL: secret://DATABASE_URL
  CRON_SECRET: secret://CRON_SECRET

Il testo secret://DATABASE_URL indica ad Adios di caricare il valore memorizzato. Non è la password della base di dati. Aggiungi solo le variabili usate dall’applicazione. Segreti e configurazione Adios

Per un’impostazione pubblica necessaria durante la compilazione, aggiungi un blocco build.env. Sostituisci questo indirizzo di esempio con quello che intendi usare:

build:
  env:
    NEXT_PUBLIC_SITE_URL: https://app.example.com

Se il server legge l’impostazione anche durante l’esecuzione, inseriscila anche sotto env. Se la compilazione richiede un valore privato, usa un riferimento a un segreto in build.env. Non inserire valori privati nel file. Riferimento del manifest Adios

Dopo aver installato la CLI di Adios, accedi, elenca i tuoi team e seleziona quello usato per Secrets:

adios login
adios teams
adios teams switch YOUR_TEAM_ID
adios up

Sostituisci YOUR_TEAM_ID con l’ID del tuo team. Esegui questi comandi dalla cartella che contiene adios.yaml. adios up carica e compila l’applicazione, avvia una versione e attende i controlli di integrità. Apri l’URL generato al termine. Deploy su Adios

Su un altro hosting, segui le sue istruzioni di deploy e poi continua con gli stessi controlli di attività e applicazione.

4. Sostituisci Vercel Cron con un altro sistema di pianificazione

Mantieni la route attuale dell’attività

Salta questa sezione se l’applicazione non usa attività programmate.

Un’attività cron è un lavoro eseguito secondo una pianificazione, come inviare un report o eliminare record scaduti. Con Vercel Cron, il codice si trova nell’applicazione e Vercel chiama il suo URL. Spostare il codice non programma l’attività sul nuovo hosting.

Per esempio, potresti avere questo in vercel.json:

{
  "crons": [
    { "path": "/api/cron/daily-report", "schedule": "0 8 * * *" }
  ]
}

Questa configurazione richiede un’esecuzione giornaliera di /api/cron/daily-report alle 08:00 UTC. Puoi mantenere la route e farla chiamare da un altro sistema di pianificazione. Attività cron Vercel

Proteggi la route. Se controlla già il valore Vercel CRON_SECRET, copia quell’impostazione privata nella nuova applicazione. Il nuovo sistema di pianificazione deve inviare un header Authorization contenente Bearer seguito dallo stesso segreto. La route deve rifiutare credenziali mancanti o errate prima di eseguire qualsiasi operazione. Proteggere le attività cron di Vercel

Facoltativo: esegui l’attività con un workflow Adios

Un workflow Adios può chiamare la route esistente e mostrare il risultato di ogni esecuzione. Puoi anche usare un altro sistema di pianificazione che supporti richieste HTTPS e header di autenticazione.

Mantieni il codice dell’attività e sostituisci il trigger. Scegli un intervallo o una pianificazione a orario fisso in base alle esigenze dell’attività.

Inizia con un’esecuzione manuale. In Segreti dello stesso team Adios, crea CRON_AUTHORIZATION. Il valore deve essere l’header completo, Bearer seguito dal valore attuale di CRON_SECRET. L’applicazione usa CRON_SECRET per controllare la richiesta; il workflow usa CRON_AUTHORIZATION per inviarla.

Crea workflows/daily-report.yaml. Tienilo separato dal file principale dell’applicazione, adios.yaml:

workflow_id: daily-report
title: Daily report
team_id: YOUR_TEAM_ID
enabled: true
version: "1"

steps:
  - step_id: call-report
    name: Run the existing report route
    kind: http
    timeout_seconds: 30
    command:
      method: GET
      url: https://your-app.example.com/api/cron/daily-report
      headers:
        Authorization: secret://CRON_AUTHORIZATION

Sostituisci l’ID del team e l’URL con i tuoi. Per questa prima esecuzione, usa un deploy di test collegato a dati di test: anche un’esecuzione manuale invia le e-mail o modifica i record previsti dalla route. Mantieni il percorso esatto della configurazione cron attuale. Il riferimento al segreto deve occupare l’intero campo dell’header: scrivere Bearer secret://CRON_SECRET invierebbe quel testo alla lettera. Segreti dei workflow Adios

Esegui il deploy del workflow:

adios workflow deploy ./workflows/daily-report.yaml

Apri Flussi di lavoro, avvia un’esecuzione manuale e controlla lo stato e l’output del passaggio. Conferma che il report sia stato generato o che la base di dati sia stata modificata. Verifica anche che una richiesta senza autorizzazione venga rifiutata. Aumenta timeout_seconds solo se la route lo richiede e l’hosting consente richieste di quella durata. Creare e controllare un’esecuzione di workflow

Poi scegli l’orario di cui hai realmente bisogno:

Esigenza	Come programmarlo
Ripetere ogni 24 ore; l’ora esatta non conta	Aggiungi un trigger a intervalli di Adios
Eseguire alle 08:00 UTC o a un’ora locale precisa	Usa una pianificazione a calendario per attivare il workflow tramite webhook oppure chiama direttamente la route protetta

Per l’opzione a intervalli, aggiungi questo blocco al livello principale del file del workflow:

triggers:
  - type: schedule
    interval: 24h

Un intervallo di 24 ore non equivale a un’esecuzione programmata alle 08:00. Adios attualmente non interpreta espressioni cron di calendario generiche come 0 8 * * *. Un nuovo intervallo può attivarsi al controllo successivo del sistema di pianificazione, e un riavvio ne azzera il conteggio. Scegli questa opzione soltanto se il comportamento è adatto all’attività. Comportamento della pianificazione Adios

Non aggiungere il blocco dei trigger finché i controlli della prossima sezione non sono superati e non sei pronto a spostare l’attività. Punta il workflow alla nuova applicazione di produzione, disattiva la pianificazione Vercel e verifica se ci sono esecuzioni ancora in corso. Poi aggiungi il trigger e ripeti il deploy con il comando precedente. Vercel offre il controllo Disable Cron Jobs per l’intero progetto; se stai spostando una sola attività, rimuovine la configurazione ed esegui un nuovo deploy su Vercel. Gestire le attività cron di Vercel

Rendi sicure le esecuzioni ripetute. Per un report giornaliero, registra la data già inviata e rifiuta i duplicati tramite un vincolo nella base di dati o una protezione equivalente contro richieste simultanee. L’attuale sistema di pianificazione di Adios non applica il campo concurrency, quindi questa impostazione non impedirà esecuzioni sovrapposte.

5. Prova l’applicazione al nuovo URL

Ripercorri le azioni abituali di un cliente

Mantieni il dominio principale sull’applicazione esistente mentre provi il nuovo indirizzo. Se usi un provider di autenticazione esterno, registra il nuovo URL di callback prima di accedere. Usa account e modalità di pagamento di test quando disponibili.

Prova	Risultato previsto
Apri la pagina iniziale e una pagina interna	Entrambe le pagine si caricano, con stili, immagini e script
Accedi, aggiorna la pagina ed esci	La sessione si comporta come previsto
Crea o modifica un record di test	La modifica viene salvata e resta visibile dopo l’aggiornamento
Carica e apri un file	Il file funziona e i file privati restano privati
Apri l’URL privato di un altro account	L’accesso viene rifiutato
Attiva un webhook di pagamento di test, se utilizzato	Lo stato di pagamento atteso cambia una sola volta
Esegui manualmente un’attività programmata	Compare il risultato previsto senza azioni duplicate

Un test dei webhook deve verificare cosa è cambiato nell’applicazione, non soltanto se l’endpoint ha risposto correttamente. Con Stripe, prova anche le consegne duplicate: la documentazione specifica che un evento può essere consegnato più volte. Guida ai webhook Stripe

Se entrambe le versioni si collegano ai dati di produzione, entrambe possono modificarli. Controlla le attività di test e lascia disattivate le operazioni distruttive finché non sei pronto al passaggio.

Usa i log per correggere i problemi

In Adios, questi comandi mostrano i log di compilazione e dell’applicazione in esecuzione:

adios logs --build
adios logs --runtime

Su un altro hosting, apri la vista equivalente dei log. Parti dal primo errore pertinente:

Sintomo	Primo controllo da fare
La compilazione segnala una variabile mancante	È disponibile durante la compilazione?
L’applicazione parte, ma l’hosting la considera non disponibile	Il comando di avvio, la porta e l’URL di integrità coincidono?
La connessione del database fallisce	L’impostazione di connessione è corretta e la base di dati consente l’accesso da questo hosting?
L’accesso reindirizza al vecchio URL	Aggiorna l’URL di callback del provider di autenticazione e l’URL dell’applicazione
L’impostazione dell’URL pubblico mostra ancora il vecchio valore	Ricompila dopo aver modificato la variabile pubblica di compilazione
L’attività restituisce `401 Unauthorized`	Controlla il segreto dell’applicazione e l’header completo di autorizzazione del workflow

Prova le funzioni particolari dell’applicazione dal nuovo URL pubblico. In una chat IA, verifica che il testo arrivi progressivamente. Per le pagine in cache, modifica dati di test e controlla che i visitatori vedano il cambiamento. Se usi più istanze, segui le indicazioni di Next.js sulla cache condivisa e sulle altre impostazioni per più server. Hosting autonomo di Next.js

6. Sposta il dominio dopo aver superato i controlli

Aggiungi il dominio, poi aggiorna il DNS

Il DNS indica ai browser dove trovare il dominio. Prima di modificarlo, salva i record attuali per poterli ripristinare se necessario.

Aggiungi il dominio personalizzato al nuovo hosting e segui le istruzioni per verifica, DNS e HTTPS. Per Adios, consulta la guida alla configurazione dei domini. Usa i record forniti per la tua applicazione; evita di copiare indirizzi da un esempio non pertinente.

Se hai usato un URL temporaneo durante i test, aggiorna gli URL dell’applicazione e di callback per il dominio definitivo. Ricompila i valori pubblici modificati. Controlla anche le destinazioni dei webhook e l’URL del workflow.

Dopo l’aggiornamento DNS, apri il dominio e ripeti i controlli di accesso, lettura e scrittura di test, e immagini. Conferma di vedere la versione prevista. Alcuni visitatori potrebbero ancora raggiungere la vecchia applicazione finché non scadono i record DNS in cache: mantieni entrambe le versioni compatibili con la base condivisa durante il passaggio.

Mantieni un modo per tornare all’applicazione funzionante

Lascia disponibile il deploy precedente mentre controlli quello nuovo. Salva la revisione funzionante del codice e le sue impostazioni, insieme ai vecchi record DNS.

Se una funzione essenziale non funziona, come l’accesso o il salvataggio dei dati, puoi ripristinare il routing precedente mentre indaghi, purché la vecchia applicazione resti compatibile con la base di dati attuale. Una modifica DNS richiede tempo per raggiungere tutti e non annulla le modifiche ai dati né le e-mail già inviate.

Annota quale sistema di pianificazione è attivo. Riportare il sito su Vercel non significa necessariamente riattivare le sue attività cron. Prendi questa decisione separatamente, affinché solo il sistema previsto esegua il lavoro.

7. Usa una lista finale di verifica

Conferma che l’applicazione sia pronta per i visitatori

La compilazione di produzione riesce e il nuovo URL serve la versione prevista.
Le impostazioni necessarie sono disponibili durante la compilazione o l’esecuzione, secondo necessità.
Funzionano l’accesso, le modifiche ai dati, le immagini e i caricamenti.
Le pagine e i file privati restano protetti.
Le integrazioni di pagamento ed e-mail hanno superato i relativi test.
Ogni attività programmata ha un sostituto testato, con tempi e autenticazione adeguati.
Il vecchio sistema di pianificazione è disattivato prima di avviare quello nuovo.
Il dominio funziona in HTTPS, inclusi gli URL di callback e di webhook.
La versione precedente funzionante e i record DNS sono disponibili per un eventuale ripristino.

Controlla la prima vera esecuzione programmata

Dopo il trasferimento, controlla i log, un normale percorso cliente e la prima attività programmata. Un test manuale dimostra che l’attività può essere eseguita; la prima esecuzione programmata verifica anche il trigger.

Conserva l’elenco dei servizi e i risultati dei test nel progetto. Renderanno più facile controllare il prossimo deploy.

Per approfondire come eseguire il server Node autonomamente, leggi Eseguire Next.js come server Node senza Lambda. Se vuoi usare Adios, la Guida alla distribuzione di Next.js illustra la configurazione della piattaforma.