Desplegar una aplicación Next.js en un VPS

Next.js suele asociarse a una plataforma de alojamiento concreta, pero su servidor Node.js standalone funciona perfectamente en cualquier VPS. El autoalojamiento resulta pertinente en cuanto usted utiliza de forma intensiva el SSR, la ISR (regeneración estática incremental) o las rutas API: estas funcionalidades consumen invocaciones facturadas en las plataformas gestionadas, mientras que son gratuitas e ilimitadas en su propio servidor. Usted controla la caché ISR en disco, el ancho de banda de las imágenes optimizadas y el tiempo de ejecución de las funciones, sin límite de 10 segundos.

La compilación de Next.js consume mucha memoria: prevea al menos 2 GB de RAM (4 GB para un proyecto grande con muchas páginas), ya que de lo contrario la compilación puede fallar por falta de memoria. Del lado del runtime, 1 o 2 vCPU bastan para servir el SSR. Instale Node.js 18 o 20 LTS, ya sea de forma nativa con nvm o mediante una imagen Docker node:20-alpine. Active output: 'standalone' en next.config.js para un despliegue ligero.

Un build Docker multi-stage reduce la imagen final a lo esencial y evita incluir las herramientas de compilación en producción. La estrategia de tres etapas — deps, builder, runner — es la más habitual para Next.js en modo standalone.

# Etapa 1 — dependencias
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# Etapa 2 — compilación
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Etapa 3 — runner (imagen final)
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

La etapa deps instala únicamente las dependencias de producción (--omit=dev). La etapa builder copia el código fuente completo y ejecuta npm run build. La etapa runner contiene solo la carpeta standalone generada por Next.js, los activos estáticos y la carpeta public.

Next.js distingue dos familias de variables según su alcance.

Variables públicas (NEXT_PUBLIC_*): se incluyen en el bundle JavaScript en tiempo de compilación y quedan expuestas al navegador. Adecuadas para una URL de API pública, un ID de Google Analytics o un indicador de funcionalidad. Nunca coloque secretos en ellas.

Variables de servidor: se leen únicamente en el lado Node (rutas API, Server Components, getServerSideProps). Nunca se envían al cliente. Aquí viven las claves de API externas, las cadenas de conexión a la base de datos y los secretos JWT.

En el VPS, dos enfoques coexisten: inyectar las variables en el entorno del proceso PM2 mediante su archivo de ecosistema (ecosystem.config.js), o pasarlas a Docker con --env-file .env.production. El segundo es preferible: el archivo permanece en el disco del servidor, fuera del repositorio git.

Nota: las variables NEXT_PUBLIC_* deben conocerse en tiempo de compilación. Si cambia una variable pública tras el build, debe recompilar la aplicación.

Un bloque Nginx completo para Next.js va más allá del proxy_pass mínimo. Es necesario servir los activos estáticos directamente desde el disco, gestionar las cabeceras de caché, activar la compresión y transmitir correctamente la información del cliente.

upstream nextjs_upstream {
  server 127.0.0.1:3000;
  keepalive 64;
}

server {
  listen 443 ssl http2;
  server_name yourdomain.com;

  gzip on;
  gzip_types text/plain text/css application/javascript application/json image/svg+xml;

  location /_next/static/ {
    alias /home/deploy/myapp/.next/static/;
    expires 1y;
    add_header Cache-Control "public, immutable";
  }

  location / {
    proxy_pass http://nextjs_upstream;
    proxy_http_version 1.1;
    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;
  }
}

El bloque upstream con keepalive 64 mantiene un grupo de conexiones persistentes hacia Node, evitando la negociación TCP en cada petición. La directiva proxy_http_version 1.1 es obligatoria para que las conexiones keepalive funcionen realmente.

La ISR (Incremental Static Regeneration) permite a Next.js regenerar una página estática en segundo plano tras un retardo dado, sin una recompilación completa. En un VPS, esto requiere que la caché sobreviva a los reinicios.

// app/productos/[id]/page.tsx (App Router)
export const revalidate = 3600; // regenerar cada hora

La caché ISR se almacena en .next/cache. Dos opciones para que sobreviva a los redespliegues:

Opción 1 — volumen persistente: monte .next/cache fuera de la carpeta de despliegue y restáurela tras cada rebuild.

Opción 2 — cache handler Redis: para varias instancias Node o necesidad de compartir entre máquinas, Next.js soporta cache handlers personalizados desde la versión 13.4.

Para sitios con poco tráfico, la opción 1 es suficiente. La opción 2 se vuelve necesaria con varios procesos Node (cluster PM2) o varios VPS detrás de un balanceador de carga.

Desde Next.js 13 y el App Router, los componentes son Server Components por defecto. La distinción tiene consecuencias directas sobre el consumo de recursos de su VPS.

Server Components se ejecutan únicamente en el servidor. Pueden leer la base de datos directamente, acceder al sistema de archivos, y no se envían nunca al bundle JavaScript del navegador. El resultado es HTML puro, lo que reduce el tamaño del bundle del cliente y mejora los Core Web Vitals (LCP).

Client Components ('use client' al principio del archivo) se hidratan en el navegador. Son necesarios para las interacciones del usuario: eventos, estado local, hooks (useState, useEffect).

La regla práctica en un VPS: mantener los Server Components para todo lo que toca a los datos, y limitar los Client Components a las zonas de interacción.

Automatizar el despliegue evita errores humanos y garantiza que cada fusión en la rama principal desencadene una recompilación limpia. Dos soluciones habituales en VPS: GitHub Actions (si su repositorio está en GitHub) y Forgejo (forge autoalojada, alternativa de código abierto a GitHub/Gitea).

name: Deploy Next.js
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /home/deploy/myapp
            git pull origin main
            npm ci
            npm run build
            pm2 reload nextjs

En ambos casos, los secretos se configuran en los secretos del repositorio y no aparecen nunca en los registros.

PM2 es a la vez el gestor de procesos y la primera herramienta de monitorización de su aplicación Next.js. Comandos esenciales:

# Estado de los procesos
pm2 list

# Registros en tiempo real
pm2 logs nextjs

# Métricas de CPU y RAM
pm2 monit

# Reinicio sin corte de servicio
pm2 reload nextjs

Active pm2-logrotate para evitar que los archivos de registro llenen el disco:

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 7

En producción, guarde la lista de procesos tras cada cambio: pm2 save.

Tres a cinco errores se repiten sistemáticamente en el primer despliegue de una aplicación Next.js en un VPS.

ENOMEM durante npm run build
Aumente el límite de memoria de Node:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Port 3000 already in use
Identifique y detenga el proceso que ocupa el puerto:

lsof -i :3000
kill -9 <PID>

MODULE_NOT_FOUND en producción con output: 'standalone'
Copie las tres carpetas necesarias:

cp -r .next/static .next/standalone/.next/static
cp -r public .next/standalone/public

Bucle de redirección HTTPS con X-Forwarded-Proto
Asegúrese de que Nginx reenvía X-Forwarded-Proto: https y de que su aplicación lee esta cabecera para determinar el protocolo real.

La carpeta .next/cache contiene dos tipos de datos valiosos: las páginas ISR revalidadas y la caché de compilación de Webpack/SWC. Perder esta caché obliga a Next.js a regenerar todas las páginas ISR al primer acceso, lo que puede generar un pico de carga.

Establezca una copia de seguridad sencilla con rsync o tar antes de cada despliegue. La caché de Webpack acelera notablemente las recompilaciones posteriores — en un proyecto mediano, una recompilación con caché completa tarda entre un 40 y un 60 % menos que una compilación en frío.

El Marketplace de ServOrbit ofrece una plantilla Next.js Stack que configura automáticamente Node.js LTS, PM2, Nginx y PostgreSQL en su VPS. En unos minutos, su entorno de producción está listo para recibir su aplicación React SSR — sin configuración manual.

Frente a la instalación descrita en esta guía, la plantilla se encarga de la puesta en marcha inicial y le permite empezar directamente en el paso «desplegar su código».