Desplegar una aplicación Nuxt en un VPS

¿Por qué autoalojar Nuxt en un VPS?

Beneficios concretos de un Nuxt autoalojado

• Rutas de servidor server/api ilimitadas, sin facturación por llamada.
• SSR e hidratación Vue 3 servidos desde un servidor Node persistente y estable.
• Build Nitro portable (node-server), fácil de contenerizar y de reproducir.
• Caché de rutas y reglas routeRules (SSR, SSG, ISR, SWR) controladas desde el servidor.
• Varias apps Nuxt compartiendo un mismo VPS detrás de Nginx.
• Variables de entorno en runtime (runtimeConfig) gestionadas directamente en su servidor.
• Control total sobre las cabeceras HTTP (CSP, HSTS, cache-control) vía middleware Nitro.

Requisitos de hardware y software

Desplegar Nuxt paso a paso

1. 01

   Configurar el proyecto para Node

   Defina el preset Nitro en nuxt.config.ts:

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

   Declare sus secretos en runtimeConfig únicamente en el lado del servidor — nunca en runtimeConfig.public. En el VPS, instale Node.js 20 LTS con nvm install 20 && nvm use 20 && nvm alias default 20, luego PM2 de forma global: npm install -g pm2.

2. 02

   Compilar la aplicación

   Clone el repositorio e instale las dependencias:

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

   Nitro produce una carpeta .output autónoma que contiene server/index.mjs y los assets estáticos en .output/public. Esa carpeta es todo lo que el VPS necesita para servir la aplicación en producción — también puede ensamblarla en CI y transferirla por rsync para evitar el build en el servidor.

3. 03

   Crear el archivo de entorno

   Cree /srv/nuxt-app/.env con sus variables de runtime. Todas las variables con prefijo NUXT_ sobreescriben las claves correspondientes de runtimeConfig al arrancar:

   NUXT_MY_SECRET_KEY=valor-produccion
   NITRO_HOST=0.0.0.0
   NITRO_PORT=3000

   Nunca incluya este archivo en el repositorio. Asegúrese de que pertenece al usuario que ejecuta PM2 y solo es legible por ese usuario (chmod 600).

4. 04

   Arrancar el servidor Nitro con PM2

   Inicie la aplicación y configure el arranque automático:

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

   El comando pm2 startup muestra una línea para copiar y pegar que crea el servicio systemd. Ejecútela con permisos de administrador. Verifique que la aplicación está en línea: pm2 status debe mostrar el estado online.

5. 05

   Configurar Nginx como reverse proxy

   Cree /etc/nginx/sites-available/nuxt-app:

   server {
       listen 80;
       server_name sudominio.com www.sudominio.com;
   
       location /_nuxt/ {
           root /srv/nuxt-app/.output/public;
           expires 1y;
           add_header Cache-Control "public, immutable";
       }
   
       location /favicon.ico {
           root /srv/nuxt-app/.output/public;
       }
   
       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;
       }
   }

   Active el sitio y pruebe la configuración: ln -s /etc/nginx/sites-available/nuxt-app /etc/nginx/sites-enabled/ && nginx -t && systemctl reload nginx.

6. 06

   Activar HTTPS con Let's Encrypt

   Instale Certbot y el plugin de Nginx, luego genere el certificado:

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

   Certbot modifica automáticamente el bloque Nginx para escuchar en el puerto 443 y forzar la redirección HTTP → HTTPS. Verifique que X-Forwarded-Proto se transmite correctamente a Nitro — sin ello, useRequestHeaders() en el lado del servidor y las redirecciones basadas en el protocolo pueden comportarse incorrectamente. La renovación automática la gestiona el timer systemd de Certbot, comprobable con systemctl status certbot.timer.

7. 07

   Actualizar sin interrupción del servicio

   Para una actualización, el reload de PM2 (no el restart) garantiza la continuidad:

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

   PM2 lanza la nueva versión, espera a que responda y luego corta la antigua: cero downtime. Para un rollback, vuelva al commit anterior, reconstruya y recargue. Si el build se hace en CI, transfiera únicamente la carpeta .output por rsync y recargue sin reconstruir en el servidor.

Optimizar el renderizado con routeRules

Nitro server vs Docker vs Vercel/Netlify para alojar Nuxt

Desplace la tabla

Resolución de problemas: errores comunes en producción