Rutas estáticas y 404

Un sitio de contenido generado debe servir el HTML de cada ruta y devolver HTTP 404 para una página inexistente. Las nuevas compilaciones de lizardpack para Astro static, Docusaurus, VitePress, Hugo y SvelteKit adapter-static usan esa política. Las SPA de React y Vue mantienen el fallback index.html necesario para los enrutadores del navegador.

Esas compilaciones responden a una página inexistente con la página 404 propia de nginx, nunca con el 404.html del sitio. Para tener tu propia página 404, usa la configuración de nginx y el Dockerfile de abajo.

Una URL de carpeta sin barra final, como /guide para guide/index.html, recibe una redirección 301 a http://YOUR_PUBLIC_HOST/guide/, y Lizard luego la redirige a HTTPS. Enlaza la forma con barra final para evitar ambos saltos, o usa la configuración de abajo, que mantiene la redirección en HTTPS.

La configuración personalizada de abajo es opcional. Úsala para una política de enrutamiento que el framework detectado no proporcione. Las imágenes existentes conservan sus reglas anteriores hasta que las vuelvas a compilar.

Elige la política de enrutamiento

Una vista comodín de SPA puede mostrar un mensaje de página inexistente, pero el código del navegador no puede cambiar el estado HTTP de la respuesta HTML que ya se envió. Si necesitas un estado HTTP según la ruta para una SPA, usa un servidor o una configuración de rutas prerenderizadas que conozca qué rutas existen.

Configura nginx para páginas generadas

Crea nginx.conf en la raíz de la aplicación:

server {
  listen 80;
  server_name _;
  root /usr/share/nginx/html;
  index index.html;
  absolute_redirect off;
 
  location / {
    try_files $uri $uri.html $uri/ =404;
  }
 
  error_page 404 /404.html;
  location = /404.html {
    internal;
  }
}

Esto admite tanto los diseños de salida guide.html como guide/index.html. error_page sirve el 404.html generado del sitio con el estado 404; si el sitio no tiene 404.html, omite los bloques error_page y de ubicación exacta para usar el cuerpo de error predeterminado de nginx. absolute_redirect off envía la redirección de carpeta como un Location: /guide/ relativo, así que el navegador se queda en HTTPS. Mantén un único estilo de URL canónica en los enlaces y el sitemap del sitio; esta regla de búsqueda no agrega redirecciones canónicas.

Compila el sitio con la configuración

Usa este Dockerfile completo para un proyecto npm con un lockfile confirmado en el repositorio. Cambia los valores predeterminados de BUILD_SCRIPT y OUTPUT_DIR para que coincidan con la tabla de abajo:

FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
ARG BUILD_SCRIPT=build
RUN npm run "$BUILD_SCRIPT"
 
FROM nginx:alpine
ARG OUTPUT_DIR=dist
COPY --from=build /app/${OUTPUT_DIR}/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

Usa la política de páginas generadas solo cuando la app tenga esos archivos de ruta. Un fallback de SPA de SvelteKit, por ejemplo, necesita su propia política de enrutamiento. Exportación estática de Next.js tiene una receta completa con un diseño de barra final.

Excluye dependencias, salida de compilación, .git y .env* en .dockerignore. Si la compilación necesita variables públicas, escríbelas como líneas ENV antes del comando de compilación. Lizard no pasa ningún build arg salvo COMMIT_SHA, así que un ARG queda vacío. No copies secretos privados en la imagen ni en la salida del navegador.

Después de la configuración de CLI, crea un servicio con lizard add --service web y luego despliega este código fuente con lizard up --service web --port 80. Omite el paso de agregar cuando el servicio ya exista. En un servicio existente, revisa el orden de decisión de compilación: las anulaciones de comandos pueden tener prioridad sobre el Dockerfile. Un archivo de configuración por sí solo no reemplaza la configuración generada de nginx; el Dockerfile debe copiarlo a la imagen.

Verifica las respuestas HTTP

Establece SITE_URL con la URL real de prueba local o el origen desplegado, y luego reemplaza /guide/ por una página que exista:

SITE_URL=https://YOUR_PUBLIC_HOST
curl -sS -o /dev/null -w '%{http_code}\n' "$SITE_URL/"
curl -sS -o /dev/null -w '%{http_code}\n' "$SITE_URL/guide/"
curl -sS -o /dev/null -w '%{http_code}\n' "$SITE_URL/this-page-does-not-exist"

Espera 200 para páginas reales y 404 para la ruta inexistente. Si una ruta válida redirige a su forma canónica, inspecciona la redirección y luego verifica el destino. Prueba también un recurso real y una ruta inventada .js: un script inexistente no debe devolver la página de inicio como HTML con estado 200.

Por último, abre la ruta interna directamente en un navegador y vuelve a cargarla. Una navegación correcta del cliente por sí sola puede ocultar un error de enrutamiento del servidor. Revisa la URL canónica y la configuración del sitemap del framework junto con el estado HTTP antes de publicar un sitio indexado.

Consulta versiones probadas y resultados en la nube para las comprobaciones de despliegue del 9 de septiembre de 2026 y sus límites.

Actualizado 21 de octubre de 2026