Guía de despliegue en Vercel: entornos de vista previa, caché en el edge y reversiones, 2026

Vercel separa cada cambio en tres etapas: un despliegue de vista previa con su propia URL temporal, un despliegue de producción que controla el dominio en vivo, y una capa de caché en el edge que sirve a ambos. Si un lanzamiento rompe algo de todos modos, vercel rollback apunta el tráfico de producción a una compilación anterior en segundos, sin necesidad de reconstruir nada. Según la documentación de 2026, los equipos de los planes Pro y Enterprise también pueden definir entornos personalizados con nombre, hasta 12 por proyecto en Enterprise, además de los tres entornos predeterminados.

Antes de empezar

Todo proyecto de Vercel tiene tres entornos predeterminados: Local, Preview y Production. El primer despliegue de un proyecto nuevo siempre es un despliegue de producción, incluso si viene de una rama distinta a main o de una ejecución del CLI que omite el indicador de producción. Después de eso entra en juego la regla habitual: hacer push a una rama que no es la de producción, abrir un pull request en GitHub, GitLab o Bitbucket, o ejecutar vercel sin el indicador de producción, crean un despliegue de vista previa en su lugar.

Los despliegues de vista previa tienen dos formatos de URL. Una URL específica de rama siempre apunta al último commit de esa rama, útil para quien solo quiere ver "lo que hay ahora". Una URL específica de commit queda fijada a una compilación exacta, lo que necesitas cuando comparas dos estados concretos lado a lado.

Para staging tienes tres opciones, y la más adecuada depende de tu plan. Un entorno personalizado, llamado por ejemplo staging o QA, con su propio seguimiento de rama, dominio y variables, está disponible en Pro (uno por proyecto) y Enterprise (doce). Cualquier plan, incluido Hobby, puede lograr algo similar con una rama de vista previa dedicada: elige una rama persistente como staging, asígnale un dominio y añade variables de entorno específicas de esa rama. ¿Quieres verificar primero con datos reales de producción? Un despliegue de producción en pausa desactiva la opción Auto-assign Custom Production Domains en Branch Tracking, de modo que una compilación de la rama de producción espera en su URL generada, con las variables de entorno de producción reales, hasta que la promueves manualmente. La promoción asigna entonces el dominio de producción sin reconstruir nada.

Sea cual sea el flujo que elijas, combínalo con una auditoría técnica de SEO para Next.js sobre la URL de vista previa. Las redirecciones, las etiquetas canónicas y los metadatos son mucho más baratos de corregir antes de que una compilación llegue al dominio de producción que después.

Paso a paso: llevar un cambio de vista previa a producción

Despliega una vista previa. Haz push a una rama que no sea la de producción, abre un pull request en un proveedor de Git conectado, o ejecuta vercel deploy desde el CLI. Vercel también admite Vercel Drop para arrastrar una carpeta al navegador sin Git ni CLI, Deploy Hooks para disparar una compilación desde una URL única sin un nuevo commit, y la REST API para servicios que necesitan crear despliegues por HTTP. Sea cual sea el disparador, obtienes una URL única y verificable.

Verifica antes de fusionar. Visita la URL de vista previa directamente, o usa el asistente curl de vercel contra el despliegue de vista previa y el visor de logs de vercel, limitado a ese despliegue y filtrado al nivel de error, para comprobar errores en tiempo de ejecución antes de que alguien fusione el pull request.

Promueve o fusiona a producción. Fusionar con la rama de producción, o ejecutar vercel deploy con el indicador de producción, compila y apunta inmediatamente tus dominios de producción al nuevo despliegue. ¿Ya tienes una compilación de vista previa que funciona y no quieres reconstruirla? vercel promote <deployment-url> lleva esa compilación exacta directamente a producción; vercel promote status confirma que se aplicó.

Confirma qué está realmente en vivo. La pestaña Deployments del panel lista cada compilación con opciones para volver a desplegar, inspeccionar, asignar un dominio personalizado o promover a producción. Desde el CLI, vercel inspect <url> muestra el commit de git, la rama y el tiempo de compilación de cualquier despliegue, de vista previa o de producción.

Caché en el edge: de los archivos estáticos a las cabeceras Cache-Control

Los recursos estáticos (imágenes, fuentes y paquetes de JavaScript) se almacenan en caché automáticamente en la red edge de Vercel durante toda la vida del despliegue. Como los nombres de archivo tienen un hash basado en el contenido, un archivo sin cambios conserva el mismo valor en caché entre despliegues en lugar de volver a solicitarse. Las páginas que necesitan una actualización periódica en lugar de una reconstrucción completa son otro caso distinto; para eso existe la regeneración estática incremental.

Las respuestas dinámicas, cualquier cosa devuelta por una Vercel Function, no se almacenan en caché por defecto. Para que una sea cacheable, la respuesta necesita una cabecera Cache-Control explícita con s-maxage=N, opcionalmente junto con stale-while-revalidate y stale-if-error. proxy-revalidate no está soportado.

Vercel añade dos cabeceras más para un control más fino. CDN-Cache-Control fija un TTL para el edge de Vercel y cualquier otro CDN downstream, sin afectar lo que almacena el navegador. Vercel-CDN-Cache-Control limita un TTL solo a la caché de Vercel, y nunca llega al navegador ni a otro CDN. Una función podría devolver razonablemente Cache-Control: max-age=10 para el navegador, CDN-Cache-Control: max-age=60 para un CDN downstream, y Vercel-CDN-Cache-Control: max-age=3600 para el propio edge de Vercel: tres tiempos de vida distintos para tres cachés distintas en una sola respuesta.

Un puñado de condiciones descalifican silenciosamente una respuesta para que no se almacene en caché: una cabecera Set-Cookie, una directiva private, no-cache o no-store, una cabecera Vary: *, o una cabecera Vary que nombre una cabecera de alta cardinalidad como Cookie. Ese último caso no da error. Devuelve x-vercel-cache: MISS con el motivo "Vary key denied", el tipo de cosa que parece un error hasta que revisas las cabeceras de la respuesta. Las respuestas de función cacheables también tienen un límite de 10 MB (20 MB para respuestas en streaming), y el TTL máximo para s-maxage, max-age o stale-while-revalidate es de un año, aunque la retención es un esfuerzo razonable, no una garantía: un recurso poco solicitado puede ser expulsado de una caché regional antes de que expire su TTL.

Revertir un despliegue de producción fallido

Cuando producción se rompe, restaurar el servicio va primero, encontrar la causa va después. vercel rollback <deployment-url-or-id> apunta el tráfico de producción a nivel de capa de enrutamiento hacia un despliegue construido previamente, sin reconstruir nada, por lo que surte efecto en segundos. vercel rollback status confirma que se completó.

La profundidad del rollback depende de tu plan. En Hobby, vercel rollback solo puede restaurar el despliegue de producción inmediatamente anterior. Los planes Pro y Enterprise pueden apuntar a cualquier despliegue de producción anterior directamente, indicando su URL o ID específicos.

Una vez restaurado el servicio, averigua qué salió mal realmente. La lista de despliegues de producción de vercel muestra las compilaciones recientes con sus commits de git. vercel inspect <url> extrae el SHA del commit, la rama y el tiempo de compilación de uno específico, y el mismo comando con su indicador de logs de compilación muestra advertencias del momento de compilación que no bloquearon el despliegue pero sí cambiaron el comportamiento en tiempo de ejecución. Comparar la salida de logs expandida, a nivel de error, entre el despliegue bueno conocido y el roto suele acotar la causa rápidamente. Si varios despliegues salieron entre el bueno y el malo, vercel bisect, con un despliegue bueno conocido y uno malo conocido como referencia, hace una búsqueda binaria entre ellos, y puedes automatizar todo el proceso con un script de prueba donde el código de salida 0 significa bueno, distinto de 0 significa malo, y 125 significa omitir.

Errores comunes

Cachear una respuesta que todavía lleva cookies de sesión. Una cabecera Vary: Cookie no lanza un error. Desactiva silenciosamente el caché para esa ruta, así que la cabecera Cache-Control que configuraste parece no haber hecho nada.

Tratar la URL de vista previa como algo opcional. Un despliegue de vista previa es el lugar más barato para detectar una regresión, antes de que tenga un dominio de producción apuntándole. Trátalo con el mismo rigor que cualquier lanzamiento, incluida una comprobación contra tu presupuesto de rendimiento, no solo un vistazo visual.

Asumir que vercel rollback reconstruye algo. No lo hace. Durante un incidente, esperar en una cola de compilación cuando ya existe un despliegue que funciona solo alarga la interrupción.

Chocar con el límite de rollback de Hobby y pensar que es un error. Hobby solo puede retroceder un despliegue de producción a la vez. Retroceder más requiere un plan Pro o Enterprise y una URL de despliegue específica.

Juntando las tres piezas, un incidente se convierte en un cambio de enrutamiento, no en una carrera contra el reloj: un despliegue de vista previa que ya detectó la regresión, una capa de caché cuyas reglas decidiste tú mismo, y un rollback que restaura el servicio en segundos mientras buscas la causa real a tu propio ritmo. Kallos Labs usa exactamente este flujo de vista previa y promoción, con una comprobación de presupuesto de rendimiento en CI, para los sitios Next.js que construimos y mantenemos para nuestros clientes. Si estás configurando esto por primera vez, nuestro equipo de desarrollo web puede acompañarte en la configuración de CI y caché.

Preguntas frecuentes

¿En qué se diferencia un despliegue de vista previa de Vercel de uno de producción?

Un despliegue de vista previa se compila a partir de cualquier rama que no sea de producción, un pull request, o un despliegue por CLI que omite el indicador de producción, y obtiene su propia URL que nunca toca el dominio de producción. Un despliegue de producción se compila a partir de la rama de producción (normalmente main) o con el indicador de producción activado, y Vercel apunta el dominio de producción hacia él en cuanto la compilación tiene éxito.

¿Vercel almacena en caché las respuestas de API dinámicas por defecto?

No. Los archivos estáticos se almacenan en caché automáticamente, pero una respuesta de una Vercel Function solo se almacena en caché una vez que devuelve una cabecera Cache-Control con una directiva s-maxage. Sin esa cabecera, cada solicitud ejecuta la función de nuevo.

¿Hasta dónde puede retroceder vercel rollback?

En el plan Hobby, vercel rollback solo restaura el despliegue de producción inmediatamente anterior. Los planes Pro y Enterprise pueden retroceder a cualquier despliegue de producción anterior indicando su URL o ID específicos.

¿Retroceder reconstruye la aplicación?

No. vercel rollback redirige el tráfico de producción hacia un despliegue ya construido a nivel de capa de enrutamiento, por lo que surte efecto en segundos en lugar de esperar una nueva compilación.

¿Cuál es la diferencia entre Cache-Control, CDN-Cache-Control y Vercel-CDN-Cache-Control?

Cache-Control es la cabecera estándar que leen tanto el navegador como cualquier CDN. CDN-Cache-Control fija un TTL separado para el edge de Vercel y cualquier CDN downstream sin cambiar lo que almacena el navegador. Vercel-CDN-Cache-Control limita un TTL solo a la caché de Vercel, y se elimina antes de que la respuesta llegue al navegador o a otro CDN.