El despliegue en Vercel falla: cómo leer el primer error real
Cuando un proyecto funciona localmente pero su despliegue en Vercel falla, el primer error en el registro de compilación es más importante que la última línea.
Abre el proyecto en el panel de Vercel, ve a Deployments y selecciona el despliegue fallido. Expande Building en los detalles del despliegue. Una línea de cierre como exited with 1 solo informa del resultado; desplázate hacia arriba hasta el primer Error. Ese mensaje determina qué código o ajuste debes revisar.
Reproduce la compilación de producción localmente
Desde el directorio del proyecto, ejecuta:
npm run build
Si el mismo error aparece, el problema probablemente está en el código y no en la configuración de Vercel. Una compilación de producción puede detectar errores de tipo o sintaxis que el servidor de desarrollo permitió. Corrige el primer error, ejecuta la compilación nuevamente y envía el cambio al repositorio.
Los valores de .env.local no aparecen en Vercel
Como .env.local normalmente se excluye de Git, Vercel no recibe automáticamente tus variables de entorno locales. Agrega solo los valores necesarios para el despliegue en Settings > Environment Variables, y selecciona los entornos correctos.
Los cambios en las variables de entorno no se aplican retroactivamente a un despliegue existente. Agrega o actualiza el valor, luego vuelve a desplegar. Usa solo el prefijo NEXT_PUBLIC_ para valores seguros de exponer en el navegador. Estos valores se incluyen en el paquete del cliente en tiempo de compilación, por lo que nunca uses el prefijo en una clave de API o token del servidor.
Las versiones de Node.js locales y en Vercel son diferentes
Una dependencia puede funcionar en una versión de Node.js y fallar en otra. Vercel actualmente admite 20.x, 22.x y 24.x; los nuevos proyectos usan por defecto 24.x.
Ejecuta node -v localmente, luego compáralo con Settings > Build and Deployment > Node.js Version. Una versión principal declarada en package.json tiene prioridad sobre la configuración del panel:
{"engines":{"node":"22.x"}}
Module not found puede deberse a las mayúsculas del nombre de archivo
El sistema de archivos predeterminado en macOS es insensible al caso, mientras que Vercel compila en Linux, donde sí se distingue entre mayúsculas y minúsculas. Si el archivo se llama Button.tsx pero el código importa ./button, la importación puede funcionar localmente y fallar en el despliegue. Compara cada carácter en la ruta desde el error con el nombre real del archivo.
Si Cannot find module 'xxx' nombra un paquete, inspecciona package.json. Un paquete que exista solo en tu node_modules local y no se declare en dependencias no aparecerá en la instalación limpia de Vercel. Ejecuta npm install package-name y confirma también en Git la actualización de package-lock.json.
La aplicación está en un subdirectorio del repositorio
Si la aplicación está dentro de un directorio como frontend/ pero Vercel compila desde la raíz del repositorio, puede no encontrar package.json o Next.js. Cuando el registro contenga un mensaje como No Next.js version detected, establece Settings > Build and Deployment > Root Directory en el directorio de la aplicación. El cambio se aplicará a los despliegues posteriores.
El despliegue es exitoso, pero una solicitud devuelve 504
FUNCTION_INVOCATION_TIMEOUT no es un error de compilación. Es una respuesta 504 que indica que una función excedió su límite de ejecución. Con Fluid compute, la duración predeterminada actual es de 300 segundos, y 300 segundos también es el máximo del plan Hobby.
Revisa Settings > Functions para confirmar que Fluid compute está habilitado y que la duración máxima no se estableció por debajo del predeterminado. Los proyectos antiguos con Fluid deshabilitado pueden tener valores predeterminados mucho más cortos.
El límite estándar para Pro y Enterprise es de 800 segundos. En un archivo de ruta del App Router de Next.js, puedes declarar:
export const maxDuration = 800;
Las funciones de Node.js y Python pueden usar una ampliación en beta que eleva el límite de 800 a 1800 segundos. Las rutas del App Router de Next.js también pueden establecer export const maxDuration = 1800;; otros entornos o frameworks pueden requerir vercel.json. Una carga de trabajo Hobby que necesite más de 300 segundos no puede resolverse aumentando el límite, así que divide la tarea en trabajo asíncrono con un Workflow, Queue o un diseño similar.
Un error de configuración también puede detener un despliegue antes de que comience la compilación, dejando sin registro Building. En ese caso, lee directamente el mensaje del panel —por ejemplo, un error de validación vercel.json. Al pedir ayuda, incluye el primer Error, package.json y la estructura del repositorio para que alguien pueda comparar los entornos locales y en Vercel.