[Vibe Coder #4] ¿Por qué falla mi app al desplegarla?

La app está terminada. Funciona perfectamente en mi ordenador. Copio localhost:3000 de la barra de direcciones para presumir ante un amigo, pero responde: «No se abre». Finalmente la despliego y, esta vez, la app que funcionaba localmente empieza a mostrar errores en Internet.

En el vibe coding, aquí es donde más personas se frustran: en el despliegue. En este episodio explicamos qué hace exactamente un despliegue y las tres causas principales de que algo funcione localmente pero falle después.

localhost significa «mi ordenador»

localhost no es una dirección especial, sino un pronombre que significa «este ordenador». Cuando la IA dice «Comprueba localhost:3000», quiere decir que abras en el navegador de tu ordenador la app que se ejecuta temporalmente en él.

Por eso, si envías localhost:3000 a un amigo, su navegador busca la app en el ordenador de tu amigo. Naturalmente, no está allí. Mi app todavía no ha salido de mi ordenador. Además, se apaga al cerrar el programa de desarrollo o el portátil. Para convertirse en un servicio utilizable por otros hacen falta dos cosas: un ordenador encendido las 24 horas y una dirección a la que cualquiera pueda acceder.

Desplegar es mudarse

El despliegue resuelve estos dos problemas. En pocas palabras, consiste en mudar la app de mi ordenador a un servidor. «Servidor» suena grandioso, pero solo es el ordenador de otra persona, conectado a Internet y encendido las 24 horas.

Servicios como Vercel y Netlify, muy usados en vibe coding, se encargan de esta mudanza. Hacen tres cosas.

1. Alquiler de servidor: prestan ordenadores de sus centros de datos.
2. Build: convierten y comprimen el código de desarrollo para producción. Es como empaquetar la mudanza.
3. Asignación de dirección: proporcionan una dirección como 내앱.vercel.app, accesible desde cualquier lugar del mundo.

Conviene recordar la palabra build. El modo de desarrollo es permisivo y pasa por alto muchos problemas, pero el build es un inspector estricto que detecta justo antes del despliegue problemas silenciosos durante el desarrollo. Muchos casos de «funciona localmente, pero falla el despliegue» se detienen en esta fase.

Las tres causas principales de que funcione localmente pero falle al desplegar

Si la app se comporta de forma extraña tras un despliegue correcto, la causa casi seguro es una de estas tres.

1.º: No se registraron las variables de entorno. En el episodio 2 pusimos la clave de API en el archivo .env y usamos .gitignore para que Git lo ignorara. Como resultado, .env no se incluye en las cajas de la mudanza. La app del servidor no tiene la clave, así que fallan las llamadas a la IA y las conexiones a la base de datos. Registra el contenido de .env en «Environment Variables», dentro del panel del servicio de despliegue, y vuelve a desplegar. Es lo primero que debes comprobar cuando funciona localmente pero no tras el despliegue.

2.º: Falló la comprobación del build. El despliegue falla y aparecen registros en rojo. No te preocupes: copia completo el registro del build que muestra el servicio y pégalo en la IA: «Falló mostrando este registro del build. Arréglalo».

3.º: La base de datos no reconoce al nuevo invitado. Según el servicio de base de datos, hay que configurar desde dónde se permiten conexiones. Hasta ahora solo se conectaba mi ordenador; ahora se conecta el servidor, así que quizá debas ajustar la lista de permitidos o la dirección de conexión. Si das los síntomas (registros) a la IA, podrá acotar rápidamente el problema.

Dominio: poner la dirección a mi nombre

Tras el despliegue aparece una dirección como 내앱.vercel.app. Puedes usarla tal cual o añadir tu propio dominio, como myapp.com. Los dominios se alquilan por años en un registrador. Conectarlo consiste en registrar en la agenda telefónica (DNS) una regla que diga: «Si buscan este nombre, dirígelos a ese servidor». El panel del servicio de despliegue guía el proceso. La propagación por las agendas telefónicas del mundo puede tardar de unos minutos a un día, así que no te alarmes si no se abre justo después.

Rutina de comprobación de 3 minutos tras el despliegue

Pulsar el botón de despliegue no es el final. Comprueba siempre estas tres cosas para detectar la mayoría de los problemas con antelación.

1. Accede directamente a la dirección desplegada. Usa la dirección real, no el localhost del desarrollo.
2. Pulsa una vez cada función clave. Prioriza las funciones que dependen del backend y de las variables de entorno, como registrarse, guardar y llamar a la IA.
3. Si algo parece extraño, abre el menú de registros (Logs) del panel del servicio de despliegue y copia las líneas rojas a la IA. El «grito del servidor» del episodio 1 aparece justo aquí.

Resumen

• localhost significa «mi ordenador», así que enviarlo a otra persona no hará que la app se abra allí.
• El despliegue muda la app a un servidor encendido las 24 horas y le proporciona una dirección pública; servicios como Vercel se encargan del proceso.
• Las tres grandes diferencias entre local y desplegado: variables de entorno no registradas (1.º), fallo del build y configuración de conexión de la base de datos. Recordar que .env no se incluye en las cajas de la mudanza ya resuelve la mitad del problema.
• Conectar un dominio es registrarlo en la agenda telefónica (DNS), por lo que la propagación puede tardar.
• Tras el despliegue, sigue la rutina de 3 minutos: abre la dirección real → pulsa las funciones clave → revisa los registros.

El próximo episodio trata los mensajes de error: cómo leer el texto rojo sin miedo, cómo entregar correctamente los errores a la IA y cómo salir del bucle cuando la IA no consigue corregir el mismo error.