Funciona en local pero falla al desplegar — cómo solucionarlo (Vercel y Netlify)

Q: Funciona en local pero falla al desplegar — cómo solucionarlo (Vercel y Netlify) | Vibe Coding Rescue

Funciona con npm run dev, pero en Vercel/Netlify se rompe con una pantalla en blanco, Module not found o datos que no cargan. Las cinco causas reales y las soluciones exactas, en pasos sencillos para quienes no programan.

Cuando funciona en local pero se rompe tras desplegar, revisa estas cinco cosas en orden — variables de entorno, volver a desplegar, mayúsculas/minúsculas del nombre de archivo, localhost escrito a mano y el comando de build.

El síntoma

Funciona perfectamente con npm run dev en tu máquina, pero en cuanto lo subes a Vercel o Netlify aparece una pantalla en blanco, un error de build «Module not found» o datos que nunca cargan. Este es el problema más común la primera vez que despliegas una app hecha con vibe coding — y la causa casi siempre es una de estas cinco cosas.

La razón de fondo es sencilla: tu PC y el servidor de despliegue son dos «entornos» distintos. Los ajustes, archivos y URLs que solo existían en tu ordenador no están en el servidor. Repasa en orden las cinco comprobaciones de abajo y resolverás la mayoría de los casos.

1. No añadiste las variables de entorno en la plataforma de despliegue — la más común

El archivo .env de tu PC vive solo en tu PC. Normalmente no se sube a git, así que Vercel y Netlify no saben ni que existe. Eso significa que valores como las claves de API y las URLs de base de datos quedan vacíos en producción, y la app se rompe.

Solución — Vercel:

Panel de Vercel → abre tu proyecto
Menú superior Settings → barra lateral izquierda Environment Variables
Escribe la Key (p. ej. VITE_SUPABASE_URL) y el Value → marca Production, Preview y Development → Save
Ve a la pestaña Deployments → ⋯ junto al último despliegue → Redeploy

> Importante: Vercel aplica los cambios de variables de entorno solo a los despliegues *nuevos*, nunca a los existentes. Después de añadir un valor tienes que volver a desplegar para que surta efecto.

Solución — Netlify:

Panel de Netlify → abre tu sitio
Site configuration → Environment variables → Add a variable
Escribe Key/Value → Save
Pestaña Deploys → Trigger deploy → Clear cache and deploy site

Ojo: los valores que usa el navegador necesitan un prefijo concreto

Las variables de entorno que lee el código del frontend (el navegador) solo llegan a la página si llevan el prefijo correcto. Sin él, el valor vuelve como undefined.

Framework	Prefijo	Cómo se lee
Next.js	`NEXT_PUBLIC_`	`process.env.NEXT_PUBLIC_XXX`
Vite (React/Vue)	`VITE_`	`import.meta.env.VITE_XXX`
Create React App	`REACT_APP_`	`process.env.REACT_APP_XXX`

Todo lo que lleve estos prefijos queda expuesto en el bundle del navegador, así que nunca pongas un secreto real (como la contraseña de una base de datos) detrás de uno.

2. Cambiaste una variable de entorno pero no volviste a desplegar

Los valores de las variables de entorno se incrustan en el código en el momento del build y se congelan ahí. Next.js, Vite y Create React App insertan los valores durante el build. Por eso, aunque edites un valor en el panel, el valor antiguo sigue vigente hasta que reconstruyas.

Solución: Tras cambiar un valor, pulsa Redeploy (Vercel) / Trigger deploy (Netlify) una vez más para forzar un build nuevo.

3. Las mayúsculas y minúsculas de un nombre de archivo no coinciden — «Module not found»

macOS y Windows tratan Button.tsx y button.tsx como el mismo archivo (no distinguen mayúsculas). Pero Vercel y Netlify hacen el build en Linux, que sí distingue estrictamente mayúsculas de minúsculas. Así que si el archivo real es Button.tsx pero tu import usa minúsculas, pasa en local y falla al desplegar con «Module not found».

Solución: Haz que la ruta del import coincida exactamente con el nombre real del archivo, letra por letra — también los nombres de carpeta.


// Real file: src/components/Header.tsx

import Header from './components/Header'  // OK
import Header from './components/header'  // FAILS on deploy: Module not found

4. Escribiste a mano una URL de API con localhost

Si escribes una URL como http://localhost:3000 directamente en el código, funciona en local porque ese es tu propio servidor. Pero en el sitio desplegado esa dirección apunta a «el propio ordenador del visitante», así que no vuelve nada.

Solución: Mueve la URL a una variable de entorno y registra la dirección real de despliegue con el método 1.


// Wrong — a local address baked into the code
fetch('http://localhost:3000/api/users')

// Fixed — pull the address from an env var (Vite example)
fetch(`${import.meta.env.VITE_API_URL}/api/users`)

5. En local corre dev, al desplegar corre build — errores que solo salen en el build

npm run dev es un servidor de desarrollo y perdona muchos problemas. Al desplegar se ejecuta npm run build (un build de producción), que es mucho más estricto con los errores de tipos y de imports.

Solución: Antes de subir nada, ejecuta el mismo build en local para detectar los problemas por adelantado.


npm run build

El error que se imprima aquí es el motivo por el que falla tu despliegue. Corrige esos errores en local y luego sube el código.

Lista de comprobación final

¿Añadiste todos los valores del .env también en Vercel/Netlify?
¿Las variables que usa el navegador llevan el prefijo NEXT_PUBLIC_ / VITE_ / REACT_APP_?
¿Volviste a desplegar después de añadir o cambiar un valor?
¿Las rutas de los imports coinciden con los nombres reales de archivo, mayúsculas incluidas?
¿No hay ninguna URL localhost escrita a mano en el código?
¿npm run build termina sin errores en tu máquina?

Si aciertas en los seis, el problema de «funciona en local, se rompe al desplegar» casi siempre desaparece.