Déployer une application Nuxt sur un VPS

Pourquoi self-héberger Nuxt sur un VPS ?

Bénéfices concrets d'un Nuxt autohébergé

• Routes serveur server/api sans facturation par appel.
• SSR et hydratation Vue 3 servis depuis un serveur Node persistant et stable.
• Build Nitro portable (node-server) facile à conteneuriser et à reproduire.
• Cache de route et règles routeRules (SSR, SSG, ISR, SWR) maîtrisés côté serveur.
• Mutualisation de plusieurs apps Nuxt sur un même VPS derrière Nginx.
• Variables d'environnement runtime (runtimeConfig) gérées en clair sur votre serveur.
• Contrôle total sur les en-têtes HTTP (CSP, HSTS, cache-control) via le middleware Nitro.

Prérequis matériels et logiciels

Déployer Nuxt étape par étape

1. 01

   Configurer le projet pour Node

   Définissez le preset Nitro dans nuxt.config.ts :

   export default defineNuxtConfig({
     nitro: { preset: 'node-server' }
   })

   Déclarez vos secrets dans runtimeConfig côté serveur uniquement — jamais dans runtimeConfig.public. Sur le VPS, installez Node.js 20 LTS via nvm install 20 && nvm use 20 && nvm alias default 20, puis PM2 globalement : npm install -g pm2.

2. 02

   Builder l'application

   Clonez le dépôt et installez les dépendances :

   git clone https://git.votredomaine.com/votre-org/votre-app.git /srv/nuxt-app
   cd /srv/nuxt-app
   npm ci
   npm run build

   Nitro produit un dossier .output autonome contenant server/index.mjs et les assets statiques dans .output/public. Ce dossier est tout ce dont le VPS a besoin pour servir l'application en production — vous pouvez aussi l'assembler en CI et le transférer par rsync pour éviter le build sur le serveur.

3. 03

   Créer le fichier d'environnement

   Créez /srv/nuxt-app/.env avec vos variables runtime. Toutes les variables préfixées NUXT_ écrasent les clés correspondantes de runtimeConfig au démarrage :

   NUXT_MY_SECRET_KEY=valeur-en-prod
   NITRO_HOST=0.0.0.0
   NITRO_PORT=3000

   Ne commitez jamais ce fichier. Assurez-vous qu'il appartient à l'utilisateur qui fait tourner PM2 et qu'il est lisible uniquement par cet utilisateur (chmod 600).

4. 04

   Lancer le serveur Nitro avec PM2

   Démarrez l'application et configurez le démarrage automatique :

   pm2 start /srv/nuxt-app/.output/server/index.mjs \
     --name nuxt-app \
     --env-file /srv/nuxt-app/.env
   pm2 save
   pm2 startup

   La commande pm2 startup affiche une ligne à copier-coller pour créer le service systemd. Exécutez-la avec les droits administrateur. Vérifiez que l'application est bien en ligne : pm2 status doit afficher l'état online.

5. 05

   Configurer Nginx en reverse proxy

   Créez /etc/nginx/sites-available/nuxt-app :

   server {
       listen 80;
       server_name votredomaine.com www.votredomaine.com;
   
       # Assets hashés : cache long, servis directement
       location /_nuxt/ {
           root /srv/nuxt-app/.output/public;
           expires 1y;
           add_header Cache-Control "public, immutable";
       }
   
       # Fichiers statiques publics
       location /favicon.ico {
           root /srv/nuxt-app/.output/public;
       }
   
       # Tout le reste → Nitro
       location / {
           proxy_pass http://127.0.0.1:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_cache_bypass $http_upgrade;
       }
   }

   Activez le site et testez la configuration : ln -s /etc/nginx/sites-available/nuxt-app /etc/nginx/sites-enabled/ && nginx -t && systemctl reload nginx.

6. 06

   Activer le HTTPS avec Let's Encrypt

   Installez Certbot et le plugin Nginx, puis générez le certificat :

   apt install certbot python3-certbot-nginx
   certbot --nginx -d votredomaine.com -d www.votredomaine.com

   Certbot modifie automatiquement le bloc Nginx pour écouter sur le port 443 et forcer la redirection HTTP → HTTPS. Vérifiez que X-Forwarded-Proto est bien transmis à Nitro — sans cela, useRequestHeaders() côté serveur et les redirections basées sur le protocole peuvent se tromper. Le renouvellement automatique est géré par le timer systemd de Certbot, vérifiable avec systemctl status certbot.timer.

7. 07

   Mettre à jour sans interruption de service

   Pour une mise à jour, le rechargement PM2 (pas le redémarrage) garantit la continuité :

   cd /srv/nuxt-app
   git pull
   npm ci
   npm run build
   pm2 reload nuxt-app

   PM2 lance la nouvelle version, attend qu'elle réponde, puis coupe l'ancienne : zéro downtime. Pour un rollback, revenez sur le commit précédent, rebuil et rechargez. Si le build se fait en CI, transférez uniquement le dossier .output par rsync et rechargez sans reconstruire sur le serveur.

Optimiser le rendu avec routeRules

Nitro server vs Docker vs Vercel/Netlify pour héberger Nuxt

Faites défiler le tableau

Dépannage : erreurs courantes en production