Despliegue de Next.js: Vercel, Self-Hosting y Docker

Por qué es importante#

Desarrollar una aplicación de Next.js de alto rendimiento para entornos de producción requiere una comprensión exhaustiva de su arquitectura de despliegue. El App Router contemporáneo de Next.js es mucho más que una librería de renderizado: es un sistema distribuido que integra un servidor de archivos estáticos, un entorno Node.js para streaming en servidor (Streaming SSR), un servicio de optimización de imágenes bajo demanda y controladores serverless para Server Actions y Route Handlers.

El enfoque tradicional consistente en ejecutar un único proceso persistente de Node.js (pnpm run start) en un servidor virtual (VPS) se convierte rápidamente en un cuello de botella durante picos imprevistos de tráfico y requiere complejas configuraciones manuales de balanceo de carga.

La plataforma Vercel automatiza esta partición distribuyendo los artefactos entre una red Edge CDN global, Serverless Functions y workers de bajísima latencia en el Edge Runtime. No obstante, en entornos corporativos y Enterprise, las exigencias regulatorias, la residencia de datos y las políticas internas exigen el despliegue en clústeres aislados de Kubernetes. Dominar el modo Standalone Mode y la optimización de imágenes Docker multietapa es imprescindible para diseñar pipelines de CI/CD resilientes.

Modelo mental#

Durante la ejecución de next build, el compilador lleva a cabo un análisis estático exhaustivo del árbol de rutas:

1. Rutas estáticas / prerenderizadas (SSG): Páginas sin llamadas a APIs dinámicas (cookies(), headers() o peticiones sin caché) se compilan en HTML estático y se sirven directamente desde la CDN sin consumo de CPU en servidor.
2. Rutas dinámicas / streaming: Páginas que requieren contexto en tiempo de ejecución se empaquetan en chunks de servidor para su ejecución en Node.js o Edge.

Distribución de artefactos en Vercel#

En Vercel, la infraestructura particiona automáticamente los artefactos de la compilación:

• Los recursos estáticos (.next/static, fuentes web, imágenes) se transfieren a la Edge CDN global.
• Los Server Components, Server Actions y Route Handlers se aíslan en Serverless Functions independientes (AWS Lambda).
• El Middleware (middleware.ts) se ejecuta en los nodos globales de la Edge Network con latencias de respuesta mínimas.

Arquitectura de Self-Hosting (Docker y Kubernetes)#

En un despliegue autogestionado, administras contenedores de larga duración. Para evitar que cientos de megabytes de herramientas de compilación y devDependencies se cuelen en la imagen final, Next.js incorpora el analizador Node File Trace (NFT). Este genera el directorio .next/standalone, que contiene exclusivamente los módulos requeridos y el microservidor server.js.

Sintaxis y API#

Activación del modo Standalone en next.config.ts#

Para generar un artefacto de servidor de producción autónomo y mínimo, añade la propiedad output: 'standalone':

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // Genera un servidor mínimo empaquetado en .next/standalone
  output: 'standalone',

  // Opcional: configuración de Cache Handler para clústeres Kubernetes (Redis)
  // cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.js') : undefined,
};

export default nextConfig;

Dockerfile multietapa canónico con soporte para pnpm#

El siguiente Dockerfile multietapa sigue los estándares contemporáneos de contenedorización utilizando Node.js 22, Alpine Linux y Corepack con pnpm:

# 1. Etapa base con Corepack y pnpm habilitados
FROM node:22-alpine AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable

# 2. Capa de dependencias (cacheada agresivamente)
FROM base AS deps
WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 3. Etapa de compilación de la aplicación
FROM base AS builder
WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Deshabilitar telemetría durante la compilación en Docker
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production

RUN pnpm run build

# 4. Imagen final de ejecución ultraligera (Runner)
FROM node:22-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000
# Crítico: Vincular el servidor a todas las interfaces de red del contenedor
ENV HOSTNAME="0.0.0.0"
ENV NEXT_TELEMETRY_DISABLED=1

# Seguridad: Creación de usuario y grupo sin privilegios
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Copia de archivos estáticos y servidor compilado en modo standalone
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

# Arranque del microservidor autónomo de Node.js sin el CLI de Next.js
CMD ["node", "server.js"]

Patrones prácticos#

1. Segregación de variables de entorno (Build-Time vs Runtime)#

En Next.js, las variables de entorno se dividen estrictamente según su ciclo de vida:

1. Variables de cliente (NEXT_PUBLIC_*): Se insertan de forma estática en el código JavaScript de cliente durante la compilación (next build). Modificarlas en el contenedor en ejecución no surte ningún efecto sin recompilar.
2. Secretos de servidor (DATABASE_URL, AUTH_SECRET): Se leen dinámicamente desde process.env en el servidor con cada petición HTTP entrante.

import 'server-only';
import { z } from 'zod';

const ServerEnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  AUTH_SECRET: z.string().min(32),
});

// Validación segura de variables al iniciar el contenedor
export const env = ServerEnvSchema.parse(process.env);

2. Caché distribuida en Kubernetes mediante Cache Handler#

Al escalar horizontalmente mediante HPA en Kubernetes, cada pod cuenta con su propio disco .next/cache aislado. Si una Server Action invoca revalidateTag(), solo el pod que gestionó la mutación purga su caché local, provocando inconsistencias para los usuarios. La solución consiste en delegar la Data Cache en Redis mediante un cacheHandler personalizado.

const { IncrementalCache } = require('@neshca/cache-handler');
const createRedisHandler = require('@neshca/cache-handler/redis-strings').default;
const { createClient } = require('redis');

IncrementalCache.onCreation(async () => {
  const client = createClient({ url: process.env.REDIS_URL });
  await client.connect();

  const redisHandler = await createRedisHandler({ client });

  return {
    cacheHandlers: [redisHandler],
  };
});

module.exports = IncrementalCache;

Errores comunes#

Preguntas de entrevista#