Guía completa para desplegar Next.js en Vercel: variables de entorno, dominio personalizado y monitorización de rendimiento

En el navegador aparece la página de error 500 de Vercel. Las variables de entorno están en el Vercel Dashboard, pero la API sigue devolviendo undefined. Revisaste .env.local tres veces, redeployaste dos veces e incluso vaciaste la caché del navegador — y nada.

Media hora después descubriste que el problema era el prefijo NEXT_PUBLIC_.

¿Te ha pasado algo parecido? El proyecto Next.js va perfecto en local y, al desplegar en Vercel, aparecen fallos raros: variables que no aplican, dominio personalizado que sigue en 404 o certificado SSL que provoca redirecciones infinitas.

El flujo de despliegue en Vercel es sencillo, pero «sencillo» y «sin trampas» no son lo mismo. Las trampas que esconden los detalles suelen volverte loco. Este artículo recorre el flujo completo de desplegar Next.js en Vercel: desde el despliegue con un clic hasta la configuración correcta de variables de entorno, la vinculación del dominio y la monitorización de rendimiento. Y marca todas las trampas que la documentación no cuenta a tiempo pero que casi seguro pisarás.

Despliegue básico (en línea en 5 minutos)

Cómo hacer bien el despliegue con un clic

El proceso en Vercel es realmente simple: subes el código a GitHub, conectas Vercel, haces unos clics — y listo. Pero detrás de esa «simplicidad» hay bastantes detalles.

Empieza por lo básico. Tu proyecto Next.js debe estar en un repositorio Git (GitHub, GitLab o Bitbucket). Luego abre vercel.com, inicia sesión con GitHub y haz clic en «Import Project».

Vercel escanea el repositorio, detecta Next.js y configura automáticamente el comando de build y el directorio de salida. Casi no tienes que tocar nada:

Build Command: next build
Output Directory: .next
Install Command: npm install

Haz clic en Deploy, espera uno o dos minutos y obtendrás una URL your-project.vercel.app. En ese momento Vercel ya ha distribuido tus recursos estáticos (JS, CSS, imágenes) en la Edge Network — CDN global, listo para usar.

Pero hay un detalle que muchos principiantes pasan por alto: revisa tu package.json.

Si el script build no es next build, o faltan next, react y react-dom en las dependencias, el despliegue fallará directamente. He visto a alguien poner webpack como script de build y no entender por qué no desplegaba: Vercel nunca encontró Next.js.

También está el flujo DPS — Develop, Preview, Ship. Suena pomposo, pero en realidad es:

• Develop: desarrollo local, npm run dev
• Preview: al crear un Pull Request o hacer push a una rama que no sea main, Vercel genera una URL de preview para probar
• Ship: al fusionar en main, Vercel despliega automáticamente a producción

Este mecanismo es muy útil. Desarrollas una función nueva, abres un PR y Vercel genera un enlace your-project-git-feature-branch.vercel.app que puedes enviar a producto o QA sin tocar producción.

Lo primero tras desplegar: revisar los logs de build

No celebres demasiado pronto. Abre el Vercel Dashboard, entra en tu proyecto, ve a la pestaña «Deployments» y abre el despliegue más reciente.

Verás logs detallados de compilación. Te indican:

1. Cuánto tardó la instalación de dependencias: si supera 1 minuto, puede que node_modules sea muy grande o la red vaya lenta
2. Si hubo avisos en el build: errores de tipos TypeScript, advertencias de ESLint
3. Cuántas páginas estáticas se generaron: Next.js te dice cuáles son SSG (Static Site Generation) y cuáles SSR (Server-Side Rendering)

En mi primer despliegue el log mostraba un montón de errores TypeScript, pero el despliegue «funcionó». Después supe que Vercel no bloquea el despliegue por errores TypeScript por defecto — salvo que actives typescript.ignoreBuildErrors: false en next.config.js.

Otro punto fácil de olvidar: un build exitoso no garantiza que la página funcione.

He visto despliegues correctos que devolvían 500 al abrir la página. Al final resultó que la ruta API usaba el módulo fs de Node.js para leer archivos locales — las Edge Functions no soportan el sistema de archivos. Las Serverless Functions de Vercel están aisladas; cada petición corre en un entorno independiente. No puedes asumir que los archivos persistan.

Configuración de variables de entorno (donde más se tropieza)

Tres niveles de entorno

Aquí viene lo importante. Las variables de entorno pueden liarte; la primera vez me quedé media hora atascado.

Vercel divide los entornos en tres: Production (producción), Preview (preview) y Development (desarrollo). En resumen:

• Production: el entorno real que ven los usuarios, ligado a tu rama main
• Preview: el entorno de prueba que Vercel genera al abrir un PR o hacer push a otras ramas
• Development: tu entorno local con npm run dev

Puedes definir variables distintas en cada uno. Por ejemplo, la cadena de base de datos: producción usa la BD real, preview una de prueba y desarrollo la local.

¿Cómo configurarlo en local?

Crea .env.local o .env.development en la raíz del proyecto:

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here

.env.local queda fuera de Git (recuerda añadirlo a .gitignore) para que tu API key no acabe en el repositorio.

¿Cómo configurarlo en Vercel?

Abre Vercel Dashboard → tu proyecto → Settings → Environment Variables.

Verás tres casillas: Production, Preview y Development. Marca en cuál debe aplicarse cada variable.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Por ejemplo, una cadena de BD solo para producción:

Name: DATABASE_URL
Value: postgresql://prod-server:5432/prod-db
Environment: ✅ Production

Tras guardar, vuelve a desplegar y la variable entrará en vigor.

Trampa habitual: no redeployar tras cambiar la configuración.

Vercel no redeploya solo. Si cambias variables de entorno, tienes que lanzar un despliegue manual (o hacer push) para que se actualicen en runtime.

Variables de cliente vs servidor

Esta es la parte más dolorosa. A las tres de la madrugada caí exactamente aquí.

Las variables de Next.js se dividen en dos tipos:

1. Variables de servidor: solo accesibles en código de servidor (rutas API, getServerSideProps, getStaticProps)
2. Variables de cliente: llevan el prefijo NEXT_PUBLIC_ y se inlined en el JS del navegador

Por ejemplo:

# Variables de servidor (seguras)
DATABASE_URL=postgresql://...
API_SECRET_KEY=abc123

# Variables de cliente (expuestas)
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Site

DATABASE_URL y API_SECRET_KEY solo existen en el servidor; el navegador no puede leerlas. Pero NEXT_PUBLIC_API_BASE_URL se compila directamente en los JS — cualquiera puede abrir DevTools y verla.

Así me equivoqué yo:

Tenía una API key para llamar a un servicio de terceros desde el cliente. Al principio no puse el prefijo NEXT_PUBLIC_ y el navegador devolvía undefined.

Luego añadí el prefijo y la key funcionó — pero quedó expuesta en el código del navegador. Cualquiera que busque NEXT_PUBLIC_ en DevTools ve la key al completo.

¿Cuál es la forma correcta?

No llames APIs de terceros directamente desde el cliente. Enruta la petición por una ruta API de Next.js:

// app/api/data/route.ts (servidor)
export async function GET() {
  const res = await fetch('https://api.example.com', {
    headers: {
      'Authorization': `Bearer ${process.env.API_SECRET_KEY}` // Seguro
    }
  })
  return res.json()
}

// app/page.tsx (cliente)
const data = await fetch('/api/data') // Tu API, sin exponer la key

Así la API key solo vive en el servidor y nunca llega al navegador.

Un detalle más: las variables NEXT_PUBLIC_ se inlined en tiempo de build, no en runtime. Si cambias una variable, tienes que volver a compilar para que surta efecto.

Trucos para sincronizar variables de entorno

En equipo, las variables son un dolor. No puedes commitear .env.local, pero quien clona el repo no sabe qué hay que configurar.

Vercel ofrece un comando:

vercel env pull .env.local

Descarga las variables de entorno (tipo Development) configuradas en Vercel a tu .env.local local.

Antes instala Vercel CLI:

npm i -g vercel
vercel link  # Vincula tu proyecto
vercel env pull

Ojo: solo trae variables de Development. Production y Preview no se descargan (por seguridad).

Otro truco: usar .env.example como plantilla.

Crea .env.example en la raíz con los nombres de todas las variables (sin valores):

# .env.example
DATABASE_URL=
API_KEY=
NEXT_PUBLIC_API_BASE_URL=

Commitea ese archivo. Quien clone el repo lo copia a .env.local y rellena sus valores.

El límite total de variables en Vercel es 64 KB; cada variable en Edge Functions, 5 KB. La mayoría de proyectos no lo alcanzan, pero si guardas claves JWT públicas o imágenes en base64, puedes toparte con el límite.

Configuración de dominio personalizado

Vincular el dominio en tres pasos

Un dominio your-project.vercel.app suena poco profesional y, además, *.vercel.app está bloqueado en China continental. Si quieres que usuarios de allí accedan con normalidad, vincular tu propio dominio es imprescindible.

Paso 1: añadir el dominio en Vercel

Abre Vercel Dashboard → tu proyecto → Settings → Domains.

Haz clic en «Add», escribe tu dominio (example.com o blog.example.com) y confirma.

Vercel detectará el dominio y te dirá qué registros DNS configurar.

Paso 2: configurar DNS

Hay dos vías: registro A y registro CNAME.

Si vinculas el dominio raíz (example.com):

Type: A
Name: @
Value: 76.76.21.21

Si vinculas un subdominio (blog.example.com):

Type: CNAME
Name: blog
Value: cname.vercel-dns.com

Configuración especial para usuarios en China:

Si tu audiencia está sobre todo en China, usa cname-china.vercel-dns.com en lugar de cname.vercel-dns.com. Es la dirección CNAME de Vercel optimizada para China continental.

Type: CNAME
Name: blog
Value: cname-china.vercel-dns.com

O un registro A hacia IPs más amigables para China:

Type: A
Name: @
Value: 76.223.126.88 o 76.76.21.98

Tras configurar DNS, espera de unos minutos a decenas (según tu proveedor). Vercel detectará cuando esté activo.

Paso 3: verificar

Vuelve al Vercel Dashboard y refresca. Si junto al dominio aparece «Valid Configuration» en verde, la configuración es correcta.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Abre el navegador, visita tu dominio y deberías ver tu proyecto Next.js.

Trampa habitual: DNS mal configurado.

He visto poner el dominio completo (blog.example.com) en el Name del CNAME en lugar de solo blog. Resultado: la resolución falla y el dominio nunca entra en vigor.

También pasa escribir mal la IP del registro A, o que la caché del proveedor DNS no se actualice y sigas viendo 404 media hora después.

Configuración automática del certificado SSL

Buenas noticias: Vercel solicita el certificado SSL (Let’s Encrypt) por ti. No hace falta configuración extra para usar HTTPS.

Cuando el dominio esté activo, Vercel pedirá el certificado en unos minutos. En Domains verás «Certificate Status: Provisioning» y pasará a «Active».

Con el certificado listo, visita https://example.com y verás el candado verde.

Pero cuidado: certificado incompatible y redirecciones infinitas.

Si configuras dominio raíz (example.com) y subdominio www (www.example.com), Vercel redirige uno al otro por defecto.

Si DNS está mal o el certificado solo cubre uno de los dos, puedes entrar en bucle — el navegador salta entre http://example.com y https://www.example.com.

Solución: añade en Vercel tanto example.com como www.example.com y configura DNS correctamente para ambos.

Algunos proveedores DNS exigen el modo «Full Encryption» en SSL/TLS. Con «Flexible Encryption» puede haber incompatibilidad de certificado.

¿Cómo comprobar que SSL funciona?

Visita https://example.com, haz clic en el candado y revisa el certificado. Si dice «Issued by: Let’s Encrypt», está bien.

O por terminal:

curl -I https://example.com

Comprueba que el código HTTP sea 200 y que exista la cabecera Strict-Transport-Security (HSTS).

Subdominios y estrategia multi-dominio

Configuración bidireccional de www y dominio raíz

Muchos configuran example.com y www.example.com y redirigen uno al otro.

En Vercel añades ambos en Domains y la plataforma gestiona la redirección. Puedes elegir «Primary Domain» en Settings; el otro redirige al principal.

Estrategia de dominios para sitios multilingües

Si tu Next.js tiene i18n, puedes usar subdominios por idioma:

• en.example.com → versión en inglés
• zh.example.com → versión en chino
• ja.example.com → versión en japonés

En Settings → Domains añade cada subdominio y configura i18n en next.config.js:

module.exports = {
  i18n: {
    locales: ['en', 'zh', 'ja'],
    defaultLocale: 'en',
    domains: [
      { domain: 'en.example.com', defaultLocale: 'en' },
      { domain: 'zh.example.com', defaultLocale: 'zh' },
      { domain: 'ja.example.com', defaultLocale: 'ja' },
    ],
  },
}

Dominio independiente para ramas de preview

Si quieres un dominio propio para preview (p. ej. la rama staging), añade staging.example.com en Domains y elige «Git Branch» = staging.

Cada push a staging desplegará en staging.example.com sin afectar producción.

Monitorización de rendimiento y optimización

Vercel Analytics y Speed Insights

Tras publicar querrás saber: ¿carga rápido? ¿Cómo es la experiencia? ¿Hay cuellos de botella?

Vercel ofrece dos herramientas gratuitas: Analytics (comportamiento) y Speed Insights (rendimiento).

Integrar Speed Insights rápido

Con Next.js App Router (13+), es muy sencillo:

npm install @vercel/speed-insights

Añade una línea en el layout raíz:

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
      </body>
    </html>
  )
}

Tras desplegar, la pestaña «Speed Insights» del Vercel Dashboard empezará a recoger datos.

Monitorización de Core Web Vitals

Speed Insights rastrea tres métricas clave de Google:

1. FCP (First Contentful Paint): tiempo hasta el primer contenido. Ideal < 1,8 s
2. LCP (Largest Contentful Paint): tiempo del contenido principal. Ideal < 2,5 s
3. CLS (Cumulative Layout Shift): estabilidad del layout. Ideal < 0,1

Los datos vienen de usuarios reales (Real User Monitoring), no del laboratorio. Ves rendimiento por región, dispositivo y navegador.

¿Cómo optimizar con Speed Insights?

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

En un proyecto mío, LCP se mantuvo en ~4 s, muy por encima de 2,5 s.

Al abrir el detalle, el problema era la imagen hero de la home — un PNG de 2 MB sin comprimir y sin el componente <Image> de Next.js.

La pasé a WebP con next/image y LCP bajó a 1,8 s. La puntuación en Speed Insights subió de 60 a 95.

Ese es el valor de los datos reales. Una puntuación de laboratorio alta no sustituye la experiencia real.

Analytics para comportamiento

Vercel Analytics muestra:

• qué páginas reciben más visitas
• de dónde vienen los usuarios
• distribución por regiones
• qué páginas tienen alta tasa de rebote

Es gratis en proyectos personales (100 000 vistas al mes); en proyectos comerciales hay que pagar.

Configuración avanzada

Comandos de build personalizados

Si tu build es especial, personalízalo en Vercel Dashboard → Settings → Build & Development Settings.

Por ejemplo, con pnpm en lugar de npm:

Build Command: pnpm build
Install Command: pnpm install

O si necesitas un script previo:

Build Command: npm run prebuild && npm run build

Edge Functions y Edge Middleware

Vercel ejecuta código en nodos edge globales (Edge Functions), con respuesta mucho más rápida que las Serverless Functions clásicas.

Si usas Middleware en Next.js, Vercel lo despliega como Edge Middleware. Autenticación, redirecciones o A/B testing pueden resolverse en el edge sin volver al origen.

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request) {
  if (!request.cookies.get('token')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

Timeout de Serverless Functions

Las Serverless Functions de Vercel tienen timeout por defecto de 10 segundos (plan gratuito). Si tu API hace operaciones lentas (llamadas externas, generar PDF), puede agotarse el tiempo.

En planes de pago puedes llegar a 60 segundos. O mueve lo pesado a colas en segundo plano (Inngest, Trigger.dev) sin bloquear la petición HTTP.

Protección de despliegue: contraseña en preview

Si no quieres preview público, activa protección en Settings → Deployment Protection.

Marca «Password Protection for Previews» y define una contraseña. Al abrir la URL de preview pedirá acceso.

Muy útil para datos sensibles o funciones a medias.

Conclusión

Con todo esto deberías tener claro el flujo completo para desplegar Next.js en Vercel.

Desde el despliegue con un clic hasta las tres capas de variables de entorno, el dominio personalizado, SSL y la monitorización avanzada — son problemas que encontrarás en proyectos reales.

Las variables de entorno enredan, pero recuerda: servidor sin prefijo, cliente con NEXT_PUBLIC_, y nunca expongas API keys en el cliente. Esa trampa ya la pisé yo por ti.

El dominio parece fácil, pero los detalles DNS fallan con facilidad. Si tienes usuarios en China, usa cname-china.vercel-dns.com o 76.76.21.21; si no, el sitio puede quedar inaccesible.

En monitorización, Speed Insights merece la pena. Los datos reales ganan a las puntuaciones de laboratorio. Si LCP supera 2,5 s, revisa imágenes, fuentes y el primer render — a menudo un ajuste sube la puntuación 30 puntos.

Ya dominas el despliegue de Next.js en Vercel. Abre la terminal, sube tu primer proyecto a GitHub, conecta Vercel y mira cómo termina el despliegue automático — esa sensación compensa estos minutos de lectura.

Si tienes dudas, comenta y trataré de responder. ¡Buen despliegue!