Hébergement Next.js
Quitter Vercel avec Next.js : guide pratique de migration
Migrez votre app Next.js hors de Vercel : réglages, tâches cron, tests et domaine, avec des exemples Adios facultatifs.
Sur cette page7 sections
Vous pouvez déplacer une application Next.js hors de Vercel sans changer de framework. Next.js fonctionne chez les hébergeurs compatibles avec Node.js. Le travail consiste à faire fonctionner les réglages, les services connectés et les tâches programmées dans le nouvel environnement. Next.js : options de déploiement
La première migration est généralement plus simple si vous conservez la base de données et le stockage, faites fonctionner l’application à une nouvelle URL, puis transférez le domaine. Vous aurez ainsi moins de problèmes à diagnostiquer en même temps.
Ce guide suit cette démarche. Vous pouvez l’appliquer chez l’hébergeur Node.js de votre choix ; les exemples Adios montrent une manière de concrétiser les étapes. Vous aurez besoin des fichiers du projet, d’un accès aux réglages Vercel et d’un accès aux réglages DNS du domaine au moment du transfert.
1. Faites une courte liste des services utilisés par votre application
Conservez les services qui fonctionnent déjà
Déplacer l’application n’impose pas de déplacer ses données. Si votre base de données accepte les connexions du nouvel hébergeur, vous pouvez généralement la conserver. Vérifiez l’existence d’une liste d’IP autorisées ou d’autres restrictions de connexion.
Procédez de même pour le stockage des fichiers, l’authentification, les paiements et les e-mails. Conservez les services qui vous conviennent s’ils sont compatibles avec la nouvelle configuration. Vercel explique par exemple comment accéder à Blob depuis l’extérieur de Vercel à l’aide d’un jeton de lecture et d’écriture. Authentification Vercel Blob
Sauvegardez une version fonctionnelle du code avant de commencer. Pour cette première migration, évitez de combiner un changement d’hébergement avec une mise à niveau du framework ou une refonte de la base de données.
Vérifiez les réglages actuellement fournis par Vercel
Ouvrez les réglages du projet Vercel et les fichiers de votre projet package.json, next.config.*, et vercel.json, s’il existe. Complétez cette petite liste :
| Élément à trouver | Information à noter |
|---|---|
| Réglages de compilation | Version de Node, gestionnaire de paquets, commande de compilation et dossier du projet |
| Variables d’environnement | Noms des variables et environnement associé : Production, Preview ou Development |
| Base de données et stockage | Services utilisés et possibilité de connexion depuis le nouvel hébergeur |
| Connexion et paiements | URL de retour et de webhook pointant vers l’application actuelle |
| Tâches cron | URL appelée par chaque tâche, fréquence et modifications effectuées |
| Domaines | Domaine utilisé par les visiteurs et endroit où son DNS est géré |
Une URL de retour est l’adresse vers laquelle un service renvoie l’utilisateur après une opération, comme une connexion. Une URL de webhook reçoit une notification d’un autre service, par exemple une mise à jour de paiement. Ces deux URL peuvent devoir changer lorsque l’adresse de l’application change.
Recherchez aussi dans votre code @vercel/ et VERCEL_. Examinez chaque résultat : certaines intégrations fonctionnent ailleurs, tandis que d’autres dépendent d’une valeur ou d’un service fourni par Vercel. Le nouvel hébergeur ne recréera pas automatiquement ces réglages.
Gardez l’ancien déploiement disponible pendant la préparation et les tests de son remplacement.
2. Vérifiez que votre application fonctionne en mode production
Compilez et démarrez l’application sur votre ordinateur
Commencez avec la version de Node et le gestionnaire de paquets déjà utilisés par le projet. Ces exemples utilisent npm et supposent que vous avez versionné un fichier package-lock.json.
Vérifiez que les scripts de package.json comprennent ces entrées. Intégrez-les aux scripts existants en conservant les étapes de compilation nécessaires à votre application.
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
Dans un terminal ouvert dans le dossier de l’application, exécutez :
npm ci --include=dev
npm run build
npm start
npm ci installe les versions enregistrées dans le fichier de verrouillage. npm run build prépare l’application pour la production. npm start lance cette version compilée. Si vous utilisez pnpm ou Yarn, employez les commandes équivalentes de votre projet. Configurer Next.js comme serveur Node
Ouvrez l’adresse locale affichée dans le terminal. Vérifiez plusieurs pages, dont une qui charge des données. Si la compilation signale un réglage manquant, ajoutez-le à l’environnement local et recommencez. Utilisez des identifiants de test pour les opérations qui envoient des e-mails, encaissent des paiements ou modifient les données de clients.
Cet exemple utilise la configuration standard next start. Si votre application utilise déjà output: 'standalone', conservez la commande de démarrage du serveur généré et incluez ses ressources pour le navigateur. Les instructions standalone de Next.js expliquent cette option de packaging.
Facultatif : décrivez la configuration pour Adios
Chez l’hébergeur choisi, configurez la commande de compilation, celle de démarrage et le port. Le port est le numéro sur lequel l’application écoute ; sa valeur doit être identique dans les réglages de l’hébergeur et de l’application.
Pour Adios, créez adios.yaml à côté de package.json. Cet exemple utilise Node 24, une instance en cours d’exécution et le port 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
Choisissez une version de Node prise en charge et compatible avec votre application, ainsi qu’une région accessible à votre équipe. Le réglage --hostname 0.0.0.0 permet à l’hébergeur de joindre l’application en cours d’exécution. Terminez l’ajout des réglages de la section suivante avant le déploiement. Le Démarrage rapide Adios explique ces champs.
Le health_path est une URL que l’hébergeur consulte pour vérifier que l’application répond. Si vous n’en avez pas, placez cet exemple App Router dans app/api/health/route.js, ou src/app/api/health/route.js si vous utilisez src/:
export function GET() {
return Response.json({ status: 'ok' })
}
Vérifiez que votre middleware d’authentification autorise cette URL sans connexion. Ce contrôle confirme que l’application répond ; il ne prouve pas que l’authentification, les paiements ou la base de données fonctionnent. Vous les testerez séparément.
3. Copiez les réglages et connectez les services
Placez chaque réglage au bon endroit
Copiez les réglages nécessaires à l’application depuis Vercel vers la configuration du nouvel hébergeur. Adaptez-les à l’environnement testé : un déploiement de test doit utiliser des clés de paiement de test et des données appropriées.
Un réglage peut être nécessaire à deux moments :
- À la compilation : pendant que
npm run buildprépare l’application. - À l’exécution : pendant que l’application compilée traite les requêtes.
| Exemple de réglage | Emplacement habituel |
|---|---|
NEXT_PUBLIC_SITE_URL | Réglages de compilation ; la valeur peut apparaître dans le navigateur |
DATABASE_URL | Réglages privés du serveur ; également à la compilation si celle-ci lit la base de données |
| Secret de signature pour l’authentification | Réglages privés du serveur, selon les instructions de votre bibliothèque d’authentification |
| Clé d’API de paiement ou d’e-mail | Réglages privés du serveur |
CRON_SECRET | Réglages privés du serveur pour l’exemple de tâche programmée ci-dessous |
Utilisez les noms réels des variables de votre application. Un nom commençant par NEXT_PUBLIC_ désigne une information qui peut être publique. N’utilisez jamais ce préfixe pour un mot de passe ou une clé d’API privée.
Next.js insère les valeurs NEXT_PUBLIC_* référencées directement dans le code du navigateur lors de la compilation. Si vous en modifiez une, recompilez l’application. Modifier uniquement un réglage d’exécution ne mettra pas à jour ce code du navigateur. Next.js : variables d’environnement
Facultatif : ajoutez les secrets Adios et déployez
Dans Adios, sélectionnez l’équipe propriétaire de l’application et créez ses valeurs privées dans Secrets. Référencez-les ensuite dans adios.yaml. Pour une application utilisant ces deux variables, ajoutez :
env:
DATABASE_URL: secret://DATABASE_URL
CRON_SECRET: secret://CRON_SECRET
Le texte secret://DATABASE_URL indique à Adios de charger la valeur stockée. Il ne s’agit pas du mot de passe de la base de données. Ajoutez uniquement les variables utilisées par votre application. Secrets et configuration Adios
Pour un réglage public nécessaire à la compilation, ajoutez un bloc build.env. Remplacez cette adresse d’exemple par celle que vous comptez utiliser :
build:
env:
NEXT_PUBLIC_SITE_URL: https://app.example.com
Si le serveur lit également ce réglage à l’exécution, ajoutez-le dans env également. Si la compilation nécessite une valeur privée, utilisez une référence à un secret dans build.env. Ne placez pas de valeurs privées dans le fichier. Référence du manifeste Adios
Après avoir installé la CLI Adios, connectez-vous, affichez vos équipes et sélectionnez celle utilisée pour Secrets :
adios login
adios teams
adios teams switch YOUR_TEAM_ID
adios up
Remplacez YOUR_TEAM_ID par l’ID de votre équipe. Exécutez ces commandes depuis le dossier contenant adios.yaml. adios up envoie et compile l’application, démarre une version et attend ses contrôles de santé. Ouvrez l’URL générée une fois l’opération terminée. Déploiements Adios
Chez un autre hébergeur, suivez ses instructions de déploiement, puis poursuivez les mêmes vérifications de tâches et d’application.
4. Remplacez Vercel Cron par un autre ordonnanceur
Conservez la route actuelle de la tâche
Ignorez cette section si votre application n’utilise pas de tâches programmées.
Une tâche cron est un travail exécuté selon un calendrier, par exemple l’envoi d’un rapport ou la suppression d’enregistrements expirés. Avec Vercel Cron, le code se trouve dans votre application et Vercel appelle son URL. Déplacer le code ne programme pas la tâche chez le nouvel hébergeur.
Vous pourriez par exemple avoir ceci dans vercel.json:
{
"crons": [
{ "path": "/api/cron/daily-report", "schedule": "0 8 * * *" }
]
}
Cette configuration demande une exécution quotidienne de /api/cron/daily-report à 08:00 UTC. Vous pouvez conserver la route et demander à un autre ordonnanceur de l’appeler. Tâches cron Vercel
Protégez la route. Si elle vérifie déjà la valeur Vercel CRON_SECRET, copiez ce réglage privé dans la nouvelle application. Le nouvel ordonnanceur doit envoyer un en-tête Authorization contenant Bearer suivi du même secret. La route doit refuser les identifiants manquants ou incorrects avant d’effectuer la moindre opération. Sécuriser les tâches cron Vercel
Facultatif : exécutez la tâche avec un workflow Adios
Un workflow Adios peut appeler votre route existante et afficher le résultat de chaque exécution. Vous pouvez aussi utiliser un autre ordonnanceur prenant en charge les requêtes HTTPS et les en-têtes d’authentification.
Conservez le code de la tâche et remplacez son déclencheur. Choisissez un intervalle ou une planification à heure fixe selon les besoins de la tâche.
Commencez par une exécution manuelle. Dans Secrets de la même équipe Adios, créez CRON_AUTHORIZATION. Sa valeur doit être l’en-tête complet, Bearer suivi de la valeur actuelle de CRON_SECRET. L’application utilise CRON_SECRET pour vérifier la requête ; le workflow utilise CRON_AUTHORIZATION pour l’envoyer.
Créez workflows/daily-report.yaml. Gardez-le séparé du fichier racine de l’application, 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
Remplacez l’ID d’équipe et l’URL par les vôtres. Pour ce premier essai, utilisez un déploiement et des données de test : une exécution manuelle envoie tout de même les e-mails ou modifie les enregistrements prévus par votre route. Conservez le chemin exact de la configuration cron actuelle. La référence au secret doit remplir tout le champ d’en-tête : écrire Bearer secret://CRON_SECRET enverrait littéralement ce texte. Secrets des workflows Adios
Déployez le workflow :
adios workflow deploy ./workflows/daily-report.yaml
Ouvrez Workflows, lancez une exécution manuelle et examinez l’état et la sortie de l’étape. Confirmez que le rapport a été produit ou que la base de données a été modifiée. Vérifiez aussi qu’une requête sans autorisation est refusée. Augmentez timeout_seconds uniquement si la route en a besoin et si l’hébergeur autorise cette durée de requête. Créer et examiner une exécution de workflow
Choisissez ensuite l’horaire réellement nécessaire :
| Besoin | Comment le programmer |
|---|---|
| Répéter toutes les 24 heures ; l’heure exacte n’a pas d’importance | Ajoutez un déclencheur par intervalle Adios |
| Exécuter à 08:00 UTC ou à une heure locale précise | Utilisez un ordonnanceur de calendrier pour déclencher le workflow par webhook, ou appelez directement la route protégée |
Pour l’option par intervalle, ajoutez ce bloc à la racine du fichier du workflow :
triggers:
- type: schedule
interval: 24h
Un intervalle de 24 heures ne remplace pas une exécution programmée à 08:00. Adios n’interprète pas actuellement les expressions cron de calendrier générales telles que 0 8 * * *. Un nouvel intervalle peut se déclencher dès la prochaine vérification de l’ordonnanceur, et le redémarrage de celui-ci réinitialise le suivi des intervalles. Choisissez cette option uniquement si ce fonctionnement convient à la tâche. Fonctionnement de la planification Adios
N’ajoutez pas le bloc de déclenchement avant que les contrôles de la section suivante soient validés et que vous soyez prêt à transférer la tâche. Pointez le workflow vers la nouvelle application de production, désactivez la planification Vercel et vérifiez si une exécution est encore en cours. Ajoutez ensuite le déclencheur et redéployez avec la commande précédente. Vercel propose le contrôle Disable Cron Jobs pour l’ensemble du projet ; si vous ne déplacez qu’une tâche, supprimez sa configuration puis redéployez sur Vercel. Gestion des tâches cron Vercel
Rendez les exécutions répétées sûres. Pour un rapport quotidien, enregistrez la date du rapport déjà envoyé et refusez les doublons à l’aide d’une contrainte de base de données ou d’une protection équivalente contre les requêtes simultanées. L’ordonnanceur actuel d’Adios n’applique pas son champ concurrency ; ce réglage n’empêchera donc pas les exécutions simultanées.
5. Testez l’application à sa nouvelle URL
Parcourez les actions habituelles d’un client
Gardez le domaine principal sur l’application existante pendant les tests de la nouvelle adresse. Si vous utilisez un fournisseur d’authentification externe, enregistrez la nouvelle URL de retour avant de vous connecter. Utilisez des comptes et des modes de paiement de test lorsqu’ils sont disponibles.
| À essayer | Résultat attendu |
|---|---|
| Ouvrez la page d’accueil et une page interne | Les deux pages se chargent, avec leurs styles, images et scripts |
| Connectez-vous, actualisez la page, puis déconnectez-vous | La session se comporte comme prévu |
| Créez ou modifiez un enregistrement de test | La modification est enregistrée et reste visible après actualisation |
| Envoyez et ouvrez un fichier | Le fichier fonctionne et les fichiers privés restent privés |
| Ouvrez l’URL privée d’un autre compte | L’accès est refusé |
| Déclenchez un webhook de paiement de test, le cas échéant | L’état de paiement attendu change une seule fois |
| Exécutez manuellement une tâche programmée | Le résultat attendu apparaît sans action en double |
Un test de webhook doit vérifier ce qui a changé dans l’application, pas seulement la réussite de la réponse de l’endpoint. Avec Stripe, testez aussi les livraisons en double : sa documentation précise qu’un événement peut être livré plusieurs fois. Guide des webhooks Stripe
Si les deux versions se connectent aux données de production, chacune peut les modifier. Maîtrisez les opérations de test et laissez les tâches destructives désactivées jusqu’au moment de leur transfert.
Utilisez les journaux pour corriger les erreurs
Dans Adios, ces commandes affichent les journaux de compilation et de l’application en cours d’exécution :
adios logs --build
adios logs --runtime
Chez un autre hébergeur, ouvrez la vue équivalente des journaux. Commencez par la première erreur pertinente :
| Symptôme | Premier point à vérifier |
|---|---|
| La compilation signale une variable manquante | Est-elle disponible à la compilation ? |
| L’application démarre, mais l’hébergeur la considère comme indisponible | La commande de démarrage, le port et l’URL de santé correspondent-ils ? |
| La connexion à la base de données échoue | Le réglage de connexion est-il correct et la base de données autorise-t-elle cet hébergeur ? |
| La connexion redirige vers l’ancienne URL | Mettez à jour l’URL de retour du fournisseur d’authentification et l’URL de l’application |
| Le réglage d’URL publique affiche encore l’ancienne valeur | Recompilez après avoir modifié la variable publique de compilation |
La tâche renvoie 401 Unauthorized | Vérifiez le secret de l’application et l’en-tête d’autorisation complet du workflow |
Testez les fonctions particulières de l’application via sa nouvelle URL publique. Pour un chat IA, vérifiez que le texte arrive progressivement. Pour les pages en cache, modifiez des données de test et vérifiez que les visiteurs voient le changement. Si vous utilisez plusieurs instances, suivez les recommandations de Next.js sur le cache partagé et les autres réglages multiserveurs. Auto-hébergement Next.js
6. Transférez le domaine après validation des contrôles
Ajoutez le domaine, puis mettez à jour le DNS
Le DNS indique aux navigateurs où trouver votre domaine. Avant de le modifier, conservez les enregistrements actuels pour pouvoir les rétablir si nécessaire.
Ajoutez votre domaine chez le nouvel hébergeur et suivez ses instructions de vérification, de DNS et de HTTPS. Pour Adios, consultez le guide de configuration des domaines. Utilisez les enregistrements fournis pour votre application ; évitez de copier des adresses provenant d’un autre exemple.
Si vous avez utilisé une URL temporaire pendant les tests, mettez à jour les URL de l’application et de retour pour le domaine définitif. Recompilez les valeurs publiques modifiées. Vérifiez aussi les destinations des webhooks et l’URL cible du workflow.
Après la mise à jour du DNS, ouvrez le domaine et répétez les contrôles de connexion, de lecture et d’écriture de test, et d’image. Confirmez qu’il s’agit de la version prévue. Certains visiteurs peuvent encore atteindre l’ancienne application tant que leurs enregistrements DNS en cache n’ont pas expiré : maintenez les deux versions compatibles avec la base de données partagée pendant la transition.
Gardez un moyen de revenir à l’application fonctionnelle
Gardez l’ancien déploiement disponible pendant les contrôles du nouveau. Sauvegardez la révision du code qui fonctionne et ses réglages, ainsi que les anciens enregistrements DNS.
Si une fonction essentielle échoue, comme la connexion ou l’enregistrement des données, vous pouvez rétablir le routage précédent pendant l’enquête, à condition que l’ancienne application reste compatible avec la base de données actuelle. Un changement DNS met du temps à atteindre tout le monde et n’annule ni les modifications de données ni les e-mails déjà envoyés.
Notez quel ordonnanceur est actif. Renvoyer le site vers Vercel ne signifie pas forcément réactiver ses tâches cron. Prenez cette décision séparément pour que seul l’ordonnanceur prévu effectue le travail.
7. Utilisez une liste finale de vérification
Confirmez que l’application peut accueillir les visiteurs
- La compilation de production réussit et la nouvelle URL sert la version prévue.
- Les réglages nécessaires sont disponibles à la compilation ou à l’exécution, selon le cas.
- La connexion, les modifications de données, les images et les envois de fichiers fonctionnent.
- Les pages et fichiers privés restent protégés.
- Les intégrations de paiement et d’e-mail ont passé leurs tests respectifs.
- Chaque tâche programmée dispose d’un remplacement testé, avec un horaire et une authentification adaptés.
- L’ancien ordonnanceur est désactivé avant l’activation de la nouvelle planification.
- Le domaine fonctionne en HTTPS, y compris les URL de retour et de webhook.
- L’ancienne version fonctionnelle et les enregistrements DNS sont disponibles en cas de retour arrière.
Vérifiez la première exécution réellement programmée
Après le transfert, vérifiez les journaux, un parcours client habituel et la première tâche programmée. Un test manuel prouve que la tâche peut s’exécuter ; la première exécution programmée vérifie également son déclencheur.
Conservez la liste des services et les résultats des tests avec le projet. Ils faciliteront la vérification du prochain déploiement.
Pour en savoir plus sur l’exécution du serveur Node par vos soins, lisez Exécuter Next.js comme un serveur Node sans Lambda. Si vous souhaitez utiliser Adios, le guide de déploiement Next.js explique la configuration de la plateforme.