trailingSlash, base y la configuración de rutas

El enrutado por ficheros dibuja un árbol de URLs limpio, pero ese árbol tiene que aterrizar en un mundo desordenado de hosts, subdirectorios y reglas de canonicidad. Cuatro claves de astro.config.mjs son las costuras donde lo ideal se ajusta a lo real: trailingSlash fija la barra final, base declara el subdirectorio, build.format decide la forma física del fichero y site da la referencia absoluta. Configurarlas bien es la diferencia entre un despliegue sin sorpresas y una tarde persiguiendo enlaces rotos.

trailingSlash: la política de la barra final

Una decisión aparentemente trivial genera sorprendentes dolores de cabeza: ¿/blog o /blog/? Para un servidor, las dos direcciones son potencialmente distintas, y tratarlas con descuido reparte tu contenido entre dos URLs, diluye el SEO y rompe cachés. La clave trailingSlash fija una política única y coherente.

import { defineConfig } from 'astro/config';

export default defineConfig({
  trailingSlash: 'never',
});

Admite tres valores, y cada uno expresa una postura:

En desarrollo, esta política se nota de inmediato: con never, visitar /blog/ devuelve un 404; con always, quien lo hace es /blog. La recomendación para un proyecto que se toma en serio su canonicidad es elegir explícitamente always o never —cuál importa menos que la consistencia— y enlazar siempre en esa forma. Dejarlo en ignore pospone una decisión que tu host y tu SEO acabarán tomando por ti, peor.

base: vivir en un subdirectorio

Por defecto Astro asume que tu sitio cuelga de la raíz del dominio. Pero a veces no es así: publicas la documentación en midominio.com/docs, o despliegas en un alojamiento que te sirve bajo el nombre del repositorio. La clave base declara ese prefijo, y a partir de ahí todas tus rutas viven bajo él.

export default defineConfig({
  site: 'https://midominio.com',
  base: '/docs',
});

Con base: '/docs', el fichero src/pages/index.astro ya no sirve / sino /docs, y src/pages/guia.astro pasa a /docs/guia. El punto delicado —y la fuente de casi todos los errores con base— es que Astro no reescribe automáticamente tus enlaces. Un <a href="/guia"> escrito a mano seguirá apuntando a /guia, fuera del subdirectorio, y se romperá. Debes incluir el prefijo tú.

Para no codificarlo a mano, Astro expone el valor en import.meta.env.BASE_URL, que refleja lo que pusiste en base. Construir los enlaces a partir de esa variable los hace inmunes a que cambies el prefijo mañana.

---
const base = import.meta.env.BASE_URL;  // '/docs'
---
<a href={`${base}/guia`}>Guia</a>

La misma cautela vale para los recursos, no solo para los enlaces. La ruta de una imagen en public, la de una hoja de estilos que referencias con URL absoluta o la de un script deben incluir el base, o apuntarán fuera del subdirectorio. Los assets que resuelve Vite —una imagen importada desde src— ya lo tienen en cuenta por ti; las rutas que escribes a mano, no. Por eso conviene concentrar la construcción de rutas en un puñado de helpers que lean BASE_URL una sola vez, en lugar de repartir el prefijo por todo el proyecto.

build.format: cómo se escriben los ficheros

Cuando Astro construye un sitio estático, debe decidir con qué forma física escribe cada página en el disco, y esa forma condiciona la URL final. La clave build.format gobierna esa decisión.

• directory —el valor por defecto— escribe cada página como ruta/index.html. Así /blog se sirve desde blog/index.html, una forma que encaja con URLs terminadas en barra.
• file escribe cada página como ruta.html. /blog sale de blog.html, más afín a URLs sin barra final.
• preserve respeta la estructura exacta de tus ficheros fuente, sin reorganizarla hacia ninguno de los dos moldes.

Que directory sea el valor por defecto no es casual. Escribir cada página como index.html dentro de su propia carpeta produce URLs que funcionan igual con o sin barra final en la mayoría de servidores, un comportamiento seguro que no exige configurar nada. file genera menos ficheros y direcciones más planas, a cambio de depender más de cómo tu host resuelve las extensiones. Elegir entre uno y otro es, en el fondo, decidir cuánto delegas en el alojamiento y cuánto controlas tú desde el build.

build.format y trailingSlash no son independientes: juntos determinan la forma canónica de tus URLs y cómo las resuelve el host. trailingSlash: 'never' conviene con format: 'file'; always casa con directory. Elegir combinaciones coherentes evita redirecciones sorpresa que algunos alojamientos aplican por su cuenta.

flowchart TD
CFG[astro config] --> TS[trailingSlash]
CFG --> B[base]
CFG --> BF[build format]
CFG --> ST[site]
TS --> POL[politica de barra final]
B --> SUB[prefijo de subdirectorio]
BF --> FIS[forma fisica del fichero]
ST --> ABS[URLs absolutas y canonicas]
POL --> URL[forma final de las URLs]
SUB --> URL
FIS --> URL
style CFG fill:#89b4fa,color:#11111b
style URL fill:#a6e3a1,color:#11111b

site: la referencia para lo absoluto

La última pieza no cambia el enrutado interno, pero es la que da sentido a las URLs absolutas. site declara la URL canónica de producción —https://midominio.com— y es la base sobre la que Astro y sus integraciones construyen direcciones completas: el sitemap, las etiquetas canónicas, las URLs de un feed RSS, las metaetiquetas de redes sociales.

Sin site, Astro.site es undefined y cualquier new URL(ruta, Astro.site) falla; con él, tienes una fuente única de verdad para el dominio. Junto con base, forman el par que responde a las dos preguntas de ubicación de todo despliegue: en qué dominio vives —site— y bajo qué subruta dentro de él —base—.

Vistas juntas, las cuatro claves componen la dirección final de tu sitio por capas. Un fichero de configuración que las declare todas se lee casi como una plantilla de URL.

// astro.config.mjs — las cuatro claves colaborando
export default defineConfig({
  site: 'https://midominio.com',
  base: '/docs',
  trailingSlash: 'never',
  build: { format: 'file' },
});

Con esta combinación, una página en src/pages/guia.astro se sirve en https://midominio.com/docs/guia, sin barra final y generada como guia.html. Cada clave ha aportado su tramo: site el dominio, base el subdirectorio, trailingSlash la ausencia de barra y build.format la forma del fichero. Leer la URL final de izquierda a derecha es, en el fondo, recorrer la configuración entera.