Publica
Next.js estático
Exporta tu app Next.js como HTML y archivos estáticos, sube el directorio `out` y publícala globalmente sin ejecutar un servidor Node.js.
Matriz de soporte para static export
Antes de subir `out`, confirma que la app encaja con el modelo estático.
Funciona bien
- Rutas estáticas generadas en build time
- Páginas de App Router que pueden renderizarse estáticamente
- Pages Router con `getStaticProps` / `getStaticPaths`
- Carga de datos del lado cliente después de hidratar
- `next/link`, imports dinámicos, CSS Modules y archivos estáticos
Necesita otro runtime
- API routes y route handlers que requieren ejecución de servidor
- Middleware, rewrites, redirects y headers personalizados
- `getServerSideProps` y render en cada solicitud
- Incremental Static Regeneration
- Optimización por defecto de `next/image` sin estrategia estática
Usa Next.js cuando quieres el framework, no el servidor
Conserva el framework y evita el runtime
Next.js static export permite conservar rutas por archivos, layouts, metadatos, render en build, CSS y React del lado cliente cuando lo necesitas.
La salida final sigue siendo archivos. Por eso encaja con sitios de marketing, docs, portafolios, páginas de producto, hubs de contenido y páginas que pueden prepararse durante el build.
Rápido como archivo estático
El HTML prerenderizado puede cachearse y servirse desde puntos de presencia sin esperar un servidor de render.
Menos operación
Sin runtime Node hay menos piezas móviles, artefactos más simples y menos diferencias entre builds y producción.
Límite de runtime claro
Si la página necesita código de servidor, no debe forzarse a static export. Si puede construirse antes, `out` es un artefacto limpio para publicar.
Bloqueos comunes de static export
El build falla por funciones solo de servidor
Quita APIs que deban ejecutarse en cada solicitud de la ruta exportada, muévelas a un back-end aparte o publica esa parte en una plataforma con runtime de servidor.
Las imágenes funcionan en dev pero fallan después de exportar
El optimizador por defecto de `next/image` espera un servidor. Usa `images.unoptimized`, un loader propio o imágenes estáticas normales.
Faltan rutas dinámicas
Genera la lista de rutas en build time con `generateStaticParams` en App Router o `getStaticPaths` en Pages Router.
Redirects o rewrites no se aplican
Los redirects y rewrites de Next.js no forman parte de static export. Usa estructura de páginas estáticas, navegación cliente o redirects de plataforma cuando estén disponibles.
Checklist para Next.js static export
Configura `output: 'export'`
Indica a Next.js que emita HTML estático durante el build en lugar de esperar `next start` o un runtime Node alojado.
output: 'export'Construye y verifica `/out`
Ejecuta el build de producción y confirma que `out` tenga páginas renderizadas, archivos, página 404 y recursos estáticos.
npm run buildSube y prueba rutas
Sube el directorio `out` y valida rutas anidadas, archivos estáticos e imágenes no optimizadas en el sitio publicado.
Preguntas frecuentes sobre Next.js
¿Por qué falla el componente Image después de exportar?
El pipeline por defecto de Image espera un servidor. Para static export, configura `images.unoptimized: true` en `next.config.js`.
¿Funcionan API routes o getServerSideProps aquí?
No. Static export elimina funciones de runtime como API routes, middleware y `getServerSideProps`. Mueve esa lógica a un back-end o servicio serverless aparte.
¿Puedo usar App Router?
Sí, siempre que la ruta pueda renderizarse estáticamente y no dependa de APIs dinámicas de servidor como headers o cookies.
¿Cómo manejo contenido dinámico?
Cárgalo durante el build cuando sea posible, o del lado cliente después de hidratar. Static export funciona mejor cuando el HTML puede prepararse antes.
¿Subo `.next` o `out`?
Sube `out` para `output: 'export'`. `.next` es un directorio interno de build de Next.js, no el artefacto estático que quieres publicar.
¿Esto reemplaza hosting Next.js con runtime?
No para todas las apps. Encaja con exports estáticos. Si dependes de SSR, middleware, ISR, server actions o API routes, necesitas un runtime que soporte esas funciones.