Exporter Next.js en statique avant l’hébergement : routes et limites

Le fait qu’une application Next.js fonctionne sur localhost ne détermine pas l’hébergement dont elle a besoin. Il faut vérifier le résultat de la compilation et les fonctions qu’elle prévoit d’exécuter à l’arrivée d’une requête. Un export statique fournit des fichiers ; une application qui nécessite une logique serveur a besoin d’un service capable de l’exécuter.

Ce diagnostic utilise un exemple original dont l’essai local est terminé et la revue indépendante approuvée. Il permet d’examiner l’artefact avant de choisir un hébergement. Il ne démontre ni une livraison native de Next.js sur Hostbrid, ni la prise en charge du SSR, de toutes les fonctions, de l’authentification ou des bases de données.

Si vous avez créé l’application avec v0 et souhaitez l’exécuter hors de Vercel, suivez le guide d’hébergement d’une app v0, qui distingue la sortie statique de Next.js des fonctions nécessitant Node.

Distinguer l’export de fichiers de l’exécution d’une application

La documentation officielle de l’export statique décrit output: 'export' : la compilation produit les fichiers qu’un serveur statique publie. Ce n’est pas équivalent à output: 'standalone', qui prépare une application à fonctionner avec Node.

La présence de Server Components ne démontre pas à elle seule qu’un serveur soit nécessaire pour chaque requête. Dans un export compatible, ils peuvent s’exécuter pendant la compilation et produire du HTML. Ce qui compte, c’est de savoir si l’application nécessite des informations ou un travail impossibles à résoudre pendant cette compilation.

Faites un inventaire avant de modifier la configuration : routes dont l’ensemble est inconnu à la compilation, cookies de l’utilisateur, actions serveur, handlers qui lisent la requête, régénération incrémentale et optimisation des images avec le loader par défaut. La documentation officielle précise les restrictions de ces fonctions. Les désactiver pour réussir la compilation peut supprimer un comportement nécessaire ; une compilation réussie ne démontre pas que l’application conserve ce qu’elle faisait.

Une route exportée possède son propre document

Une SPA classique peut avoir un seul fichier HTML que le routeur interprète dans le navigateur. Un export Next.js génère des documents par route. Si toutes les requêtes sont réécrites sans distinction vers l’accueil, /about peut renvoyer un code 200 et afficher la mauvaise page.

Une question réelle sur la publication avec cPanel décrit ce symptôme lors du rechargement d’une route. La question illustre la difficulté ; ses réponses ne remplacent ni la documentation actuelle ni un test de votre configuration.

Vérifiez l’organisation des routes dans le dossier exporté. trailingSlash modifie la disposition des fichiers : ne copiez pas les règles d’un autre site sans examiner le résultat. Testez l’accès direct, la navigation depuis une autre page et le rechargement. Vérifiez à chaque fois le contenu et l’identité de la page, en plus du code HTTP. Une route inexistante doit rester une erreur vérifiable, pas une page d’accueil déguisée en réussite.

Décider quelles routes existent pendant la compilation

Les routes dynamiques exportées nécessitent des paramètres permettant de générer leurs documents pendant la compilation. Si votre application découvre de nouveaux identifiants uniquement à l’arrivée d’une requête, ajouter une liste inventée pour faire disparaître l’erreur ne suffit pas : vous devez décider si vous pouvez régénérer et publier cet ensemble ou s’il vous faut une autre architecture.

L’exemple génère /notes/orbita/ et vérifie qu’un slug inconnu renvoie un véritable 404. En retirant generateStaticParams() de la route dynamique, la compilation s’est terminée avec le code 1 et l’erreur spécifique de Next.js signalant l’incompatibilité avec output: export. L’installation avait réussi ; un échec réseau ou de dépendances n’aurait pas compté comme ce contrôle.

Résultats de l’essai local

L’essai fixe Next.js 16.4.0, React 19.3.0, Node 22.23.3 et npm 10.9.9. Il a généré trois documents différents : l’accueil, /about/ et /notes/orbita/. Leurs octets ont été vérifiés en HTTP, ainsi que six cas Chrome à 390 et 1280 pixels, DPR 2, avec accès direct et rechargement d’un nouveau document. Le CSS, le SVG et le JavaScript ont été chargés ; un compteur est passé de 0 à 1 au clic et est revenu à 0 au rechargement. Ce compteur ne possède qu’un état en mémoire : il ne démontre pas de persistance.

Le contrôle négatif a renvoyé les octets exacts de l’accueil avec HTTP 200 lors d’une requête sur /about/. Le même vérificateur qui acceptait la bonne page a rejeté cette identité incorrecte. Cela teste une défaillance qu’une revue fondée uniquement sur le code HTTP aurait laissée passer.

La première exécution a échoué parce que le serveur local de l’essai ne décodait pas une URL de chunk contenant des crochets. Le serveur a été corrigé et une nouvelle exécution a été menée à terme. Cet échec de l’essai est conservé comme preuve ; il ne démontre pas un défaut du produit d’hébergement.

Les tests locaux identifient l’artefact exportable et ses restrictions. Ils n’évaluent pas la publication du projet sur Hostbrid et ne valident pas une application qui nécessite un serveur. Avant de déplacer votre application, vérifiez séparément les fonctions qu’elle utilise et l’identité de ses routes sur l’hébergement choisi.

Si votre application a besoin d’un serveur Next.js et pas seulement de fichiers, consultez le guide pour héberger Next.js sur un VPS. Pour vérifier un autre processus Node ou Docker, consultez le guide des ports et de l’état et les capacités réelles du produit avant de souscrire. Si votre frontend utilise un backend externe, inventoriez ce service séparément : exporter le frontend ne migre ni ses données ni ses identifiants d’accès.

Reproduire la révision vérifiée

L’exemple original sous licence MIT contient l’application et l’essai. Ces commandes fixent la révision examinée. Il vous faut Node 22.23.3 avec npm 10.9.9 et Chrome sur macOS ; consultez le README et utilisez un nouveau dossier pour conserver les preuves.

git clone https://github.com/ocentelles/hostbrid-example-next-static-export.git
cd hostbrid-example-next-static-export
git checkout 5033d51146fa992b1deb8c6080696ed3cc8da91d
node --version
node scripts/run-essay.mjs /tmp/my-next-export-evidence