Un sitio publicado puede estar en blanco incluso cuando la vista previa del editor funciona. Esa diferencia es útil: apunta primero al entorno de producción, a los activos compilados o al enrutamiento en vivo, y no a un diseño aleatorio.
Respuesta en 30 segundos
Abra la URL en vivo, abra las herramientas de desarrollo del navegador y recargue una vez. Use el primer error rojo Consola y la primera solicitud Red fallida para elegir la rama:
- la variable de entorno está faltando o
undefined→ agréguela al host de despliegue y vuelva a desplegar - JavaScript o CSS devuelve 404 → arregle la salida de compilación o la ruta base pública
Unexpected token <o un error MIME de módulo → la URL devolvió una página de error HTML en lugar de JavaScript- solo una URL anidada falla después de recargar → agregue el fallback de SPA documentado del host
- JavaScript lanza un error antes de que la aplicación se monte → arregle esa primera excepción de tiempo de ejecución
Rama 1 — Las variables de producción están faltando
Los secretos almacenados dentro de un constructor de aplicaciones no existen automáticamente en cada host externo. Compare los nombres de las variables en el proyecto con las configuradas para el entorno de producción exacto. No copie los valores de secretos en chats o capturas de pantalla.
Para una aplicación Vite del lado del cliente, solo las variables que se exponen intencionalmente con el prefijo público del marco están disponibles en el código del navegador. Nunca exponga una clave del servidor simplemente para hacer desaparecer la pantalla en blanco. Agregue o corrija la variable en la plataforma de despliegue, luego cree un nuevo despliegue; cambiar una variable no reescribe una compilación que ya existe.
Rama 2 — Los activos compilados están faltando
En el panel de Red, seleccione una solicitud fallida de JavaScript o CSS. Un 404 suele significar que la salida desplegada y la URL del activo generado no coinciden. Unexpected token < suele significar que la URL del script devolvió una página de error HTML. Un error MIME de módulo puede significar que se subieron los archivos de origen en lugar de la salida compilada.
Ejecute una compilación de producción limpia localmente:
npm run build
Despliegue el directorio que realmente genera su marco, como dist/ para un proyecto estándar de Vite. Siga la configuración actual de salida de compilación de la plataforma, en lugar de adivinar un nombre de carpeta. Si la aplicación se sirve bajo una subruta, verifique que la ruta base pública del marco coincida con esa URL real.
Rama 3 — Una ruta anidada falla al recargar
Si / funciona pero /dashboard está en blanco o 404 después de una visita directa, el router del navegador y el host no están de acuerdo. Configure el fallback de la aplicación de página única documentado por la plataforma de hospedaje para que las rutas de la aplicación devuelvan index.html. No redirija los archivos de activos o las rutas de API a index.html; eso puede producir el error Unexpected token < descrito anteriormente.
Pruebe tanto una visita directa como una recarga en una ruta anidada después de desplegar la regla de reescritura.
Rama 4 — La aplicación en vivo lanza un error de tiempo de ejecución
Empiece con la primera excepción, no con todos los mensajes que están debajo de ella. Ejemplos típicos incluyen leer una propiedad de undefined, inicializar un cliente de API sin una URL requerida, o importar código que asume que una característica del navegador está disponible.
Proporcione al agente la excepción exacta, el archivo y el número de línea. Pídale que explique por qué ese valor está faltando antes de editar. Arregle una causa, reconstruya y pruebe de nuevo la URL en vivo en una ventana privada.
Verificar la solución
Use un nuevo despliegue y confirme:
- que la compilación del despliegue se completó con éxito
- que la consola en vivo no tiene excepciones no capturadas en la primera carga
- que las solicitudes de JavaScript y CSS devuelven respuestas exitosas con el tipo de contenido esperado
/y una ruta anidada funcionen ambos en una ventana privada- que la interacción principal funcione, no solo el primer fotograma
Una pestaña en caché puede mostrar un error antiguo. Use una ventana privada o una recarga forzada para la verificación final.
Si aún no funciona
Restaure el último despliegue que funcionó, luego compare los nombres de las variables de entorno, el comando de compilación, el directorio de salida y las reglas de enrutamiento con el despliegue fallido. Si el proveedor reporta un incidente, detenga los cambios de código y espere. De lo contrario, envíe la URL del despliegue, el primer error de la consola, la primera solicitud de red fallida y el registro del despliegue a soporte oficial—después de eliminar secretos y datos personales.
Resumen para principiantes
Cuando la vista previa funciona pero el sitio publicado está en blanco, el entorno en vivo es diferente. Revise el primer error rojo de la consola, asegúrese de que el host tenga las variables requeridas, despliegue la salida compilada y pruebe una URL anidada. Cambie una rama a la vez en lugar de pedirle a la IA que reescriba la página.