El error silencioso de AWS S3 + CloudFront que arruina tu despliegue
Desplegar un sitio estático en AWS parece sencillo hasta que no lo es. S3 almacena tus archivos, CloudFront los distribuye globalmente y todo debería funcionar. Pero hay un detalle arquitectónico que la documentación oficial no explica con suficiente claridad, y que puede costarte horas de depuración: CloudFront no sabe resolver subdirectorios por defecto.
Este es uno de esos problemas que aparecen exactamente cuando ya creías que habías terminado. El sitio carga bien en la URL raíz, pero en cuanto intentas acceder a una ruta como /docs o /app, obtienes un 403, una descarga inesperada del objeto, o peor aún, la página carga pero sin CSS ni JavaScript. Todo roto, sin un mensaje de error claro.
En este artículo revisamos los cuatro casos límite más comunes al trabajar con S3 + CloudFront para hosting de subdirectorios, sus causas reales y la solución concreta que funciona. Si tu equipo trabaja con arquitecturas cloud en AWS, esto te va a ahorrar tiempo.
Por qué S3 y CloudFront no resuelven directorios automáticamente
Cuando configuras CloudFront con S3 como origen usando el REST API endpoint (el formato bucket.s3.amazonaws.com), S3 trata cada solicitud como una búsqueda de objeto exacto. No hay lógica de directorio. No existe la noción de "busca el index.html dentro de esta carpeta".
El "Default Root Object" de CloudFront, esa opción donde pones index.html, solo aplica a la raíz de la distribución. Para cualquier subdirectorio, esa configuración simplemente no existe.
El resultado concreto es el siguiente: una solicitud a /docs/index.html devuelve el HTML correcto, pero una solicitud a /docs/ descarga el objeto como archivo, y una solicitud a /docs devuelve un 403 Forbidden. Tres comportamientos distintos para lo que debería ser la misma página.
Según el análisis publicado por Vivek Vohra en Dev.to, la solución más robusta es implementar una CloudFront Function que intercepte las solicitudes antes de que lleguen al origen S3. Esta función debe hacer dos cosas: redirigir las rutas sin barra final (/docs → /docs/) y reescribir las rutas de directorio para apuntar explícitamente al index.html correspondiente.
El problema de las rutas relativas y la barra al final
Hay un segundo problema que no es de CloudFront ni de S3, sino del navegador. Y es más sutil.
Cuando un navegador carga /app/, interpreta que está dentro de un directorio y resuelve los assets relativos desde ahí. Si tu HTML referencia styles.css, el navegador busca /app/styles.css. Correcto.
Pero si el navegador carga /app sin la barra final, interpreta que app es un archivo. Entonces resuelve los assets desde la raíz: busca /styles.css en lugar de /app/styles.css. El archivo no existe ahí, y tu página carga completamente rota.
Este es exactamente el comportamiento que explica por qué /app/ muestra el sitio perfecto y /app muestra el mismo HTML pero sin estilos ni scripts. No es un problema de configuración de CloudFront. Es cómo los navegadores resuelven rutas relativas según el contexto de la URL actual.
La solución es simple pero obligatoria: siempre redirigir las rutas sin barra final a su equivalente con barra antes de servir el contenido. Esa redirección 301 tiene que ocurrir en el evento Viewer Request de CloudFront, no en el Viewer Response. Si la adjuntas al evento equivocado, obtienes un 503 porque CloudFront espera un objeto de respuesta HTTP completo, no una solicitud modificada.
Cómo aplica esto en empresas de Perú y Latinoamérica
Este tipo de arquitectura, S3 como almacenamiento y CloudFront como CDN, es cada vez más común en equipos de desarrollo de la región. Es económica, escala bien y elimina la necesidad de mantener servidores web. Muchas empresas la usan para portales de documentación interna, aplicaciones frontend en React o Vue, y sitios de marketing de alto tráfico.
El problema es que estos detalles de configuración no aparecen en los tutoriales básicos. Un equipo que despliega su primera aplicación en esta arquitectura puede pasar horas depurando un error que tiene una solución de 15 líneas de código, simplemente porque no sabía dónde buscar.
Para equipos técnicos en crecimiento, documentar estos patrones internamente es tan importante como implementarlos. Cada decisión de infraestructura que no queda registrada se convierte en deuda técnica invisible: el próximo desarrollador que toque esa configuración no va a saber por qué existe esa función de CloudFront, y si la elimina, el sitio se rompe de maneras que parecen inexplicables.
¿Cómo aplica esto en tu empresa?
Si tu equipo está usando o planea usar AWS S3 + CloudFront para hosting de aplicaciones estáticas, hay tres acciones concretas que puedes tomar hoy:
- Audita tu configuración de origen en CloudFront. Verifica si estás usando el REST endpoint o el Static Website endpoint de S3. El comportamiento de routing es diferente entre ambos y afecta directamente cómo se resuelven los subdirectorios.
- Implementa la CloudFront Function de reescritura de URLs. La lógica es sencilla y cubre los dos casos críticos: redirección de rutas sin trailing slash y reescritura a index.html. Esto elimina la mayoría de los problemas de routing en un solo paso.
- Valida siempre en ventana de incógnito durante el debugging. Los navegadores cachean agresivamente las redirecciones 301 y las políticas HSTS. Lo que ves en tu sesión normal puede estar completamente desactualizado respecto a la infraestructura real. Incógnito es la fuente de verdad durante la depuración.
Estos no son detalles menores. Son la diferencia entre un despliegue que funciona de manera confiable y uno que falla de formas inconsistentes y difíciles de reproducir.
Conclusión
AWS S3 + CloudFront es una combinación poderosa y económica para hosting de sitios estáticos, pero tiene comportamientos que no son intuitivos. El Default Root Object solo cubre la raíz, las rutas relativas dependen de la barra final, y las CloudFront Functions deben adjuntarse al evento correcto para funcionar. Conocer estos casos límite de antemano convierte horas de debugging en minutos de configuración.
En Consultoría-Ti ayudamos a equipos técnicos y empresas en Perú y Latinoamérica a diseñar y desplegar arquitecturas cloud que funcionen de manera confiable desde el primer día. Si tu equipo está trabajando con AWS o evaluando una migración a infraestructura en la nube, conversemos.
👉 Escríbenos a consultoria-ti.com.pe/contactus y cuéntanos en qué estás trabajando.
Fuentes y Referencias
AWS S3 + CloudFront Subdirectory Hosting: Architecture & Edge Cases — Vivek Vohra en Dev.to
✨ Contenido generado con ContentFlow — Consultoría-Ti