Astro SEO: cómo lograr que un sitio de Astro posicione mejor

TL;DR: Astro te da una base sólida de SEO porque pre-renderiza HTML estático y, por defecto, elimina el JavaScript del lado del cliente. Configura site en astro.config.mjs, mantén el contenido indexable fuera de componentes client:only, y configura metadatos únicos, canonicals absolutos, un sitemap y un formato de URL consistente. Luego revisa el HTML generado. Un árbol de componentes “limpio” no demuestra que la página desplegada sea rastreable.

Astro es bueno para SEO, pero no hace SEO por ti

La parte más fuerte del SEO en Astro no es un paquete de SEO. Es el modelo de renderizado de Astro.

“Por defecto, Astro renderizará automáticamente cada componente de UI a solo HTML y & CSS, eliminando automáticamente todo el JavaScript del lado del cliente.”

Así lo describe la propia Astro en su documentación de arquitectura de Islands. Astro hidrata únicamente los componentes marcados explícitamente para ejecutarse en el navegador y deja el resto de la página como HTML estático.

La diferencia importa porque Google no trata descargar JavaScript y ejecutarlo como la misma operación.

“Google procesa las apps web con JavaScript en tres fases principales: 1. Crawling 2. Rendering 3. Indexing”

Google Search Central también explica que un Chromium sin interfaz (headless) renderiza la página una vez que los recursos de Google lo permiten. Google puede renderizar JavaScript, pero el contenido que existe solo después de la ejecución depende de esa fase adicional. El HTML estático de Astro por defecto elimina esa dependencia porque el contenido relevante ya puede estar presente en la respuesta. Nuestro guía de JavaScript SEO profundiza en el mecanismo.

Esta es una ventaja técnica real. No es una ventaja automática de posicionamiento. El HTML estático no “rescata” páginas ligeras, títulos duplicados, enlaces internos débiles, canonicalizaciones accidentales o contenido que nadie necesita.

Astro ofrece una infraestructura de base excepcional. Pero tú todavía tienes que conectarlo.

Configura primero la URL del sitio en producción

Antes de añadir un componente de SEO, configura site en astro.config.mjs:

Configúralo una sola vez en tu Astro config para que canonicals y el sitemap apunten a URLs reales:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',   // habilita URLs canonical y el sitemap
  integrations: [sitemap()],
});

La Configuration Reference de Astro define site como la URL final desplegada y afirma que usa ese valor para generar los URLs del sitemap y las canonicals. El valor predeterminado es undefined y Astro recomienda encarecidamente configurarlo.

Una sola línea controla varios sistemas:

• Astro.site es undefined si no lo configuras.
• @astrojs/sitemap lo necesita para generar las URLs del sitemap.
• @astrojs/rss lo usa para crear enlaces a artículos.
• Las URLs canonical y de imagen social lo necesitan para un origen de producción fiable.

Vimos el “espejo” de esta dependencia durante nuestra migración de seojuice.io a seojuice.com en enero de 2026. Canonicals, entradas del sitemap, URLs de Open Graph y referencias internas tuvieron que converger en un único origen de producción. Una migración deja el problema al descubierto; un site olvidado oculta la misma clase de error dentro de una compilación que, por lo demás, sale bien.

Define la URL de producción, compila y revisa la salida antes de depurar integraciones aguas abajo (un origen, varios síntomas).

Construye un solo componente head, no decenas de variaciones

Astro no incluye una abstracción especial para metadatos. Los títulos y las descripciones son etiquetas HTML normales. En la mayoría de sitios, el enfoque mantenible es un layout compartido que acepte valores específicos de cada página mediante Astro.props.

La primera y la tercera línea son los cercos (frontmatter fences) de Astro. Cada página o entrada de contenido debe aportar su propio título y descripción. Un fallback es útil para detectar datos incompletos, pero no permitas que un valor predeterminado del sitio se convierta silenciosamente en los metadatos de cada URL.

Prefiero validar los metadatos requeridos durante la compilación en lugar de descubrir omisiones en Search Console semanas después. Si una página pública de contenido no tiene título o descripción, hacer fallar la compilación suele ser el comportamiento más “amable”.

¿Deberías usar el paquete astro-seo?

El paquete de la comunidad astro-seo puede envolver las etiquetas habituales. Instálalo con npm install astro-seo, importa SEO desde el paquete y renderiza el componente dentro de la cabecera (document head). En su repositorio se listan soportes para títulos, descripciones, canonicals, directivas robots, Open Graph, tarjetas de Twitter, plantillas de título, alternancias de idioma y etiquetas personalizadas.

Seamos precisos: astro-seo es un componente de terceros mantenido por jonasmerlin, no una integración oficial de @astrojs. Yo lo usaría cuando su API elimine repeticiones que realmente importan. Para un sitio de marketing pequeño, un componente head local suele ser más fácil de auditar y más difícil de “quedarse corto” (menos dependencias pueden ser una ventaja, no una preferencia estética).

Mantén los metadatos sociales junto a los metadatos de búsqueda

Open Graph y Twitter Cards son etiquetas meta estándar. Genera todo eso en el mismo componente head compartido para que el título de la página, la descripción, la URL canonical y la imagen no puedan divergir de forma independiente. Las imágenes sociales deberían usar URLs absolutas basadas en Astro.site; las rutas relativas son una causa frecuente de que las previsualizaciones funcionen en un servicio y fallen en otro.

Genera canonicals a partir del origen de producción y la ruta actual

Astro expone los dos valores necesarios para una canonical. Astro.site devuelve una URL basada en el sitio de producción configurado, mientras que Astro.url representa la URL de la solicitud actual.

El API Reference oficial muestra este patrón:

Esto combina la ruta actual con el origen de producción e impide que un hostname de desarrollo o de previsualización se convierta en canonical solo porque sirvió la petición (los hosts de previsualización no deberían “votar”).

Observa que el patrón usa Astro.url.pathname, no la URL completa de la solicitud. Por tanto, elimina los parámetros de consulta. Normalmente eso está bien para parámetros de tracking y páginas de contenido habituales, pero no es universal. La paginación, colecciones filtradas y páginas realmente distintas parametrizadas necesitan una política canonical explícita.

Una canonical no es un marcador genérico de “SEO activado”. Es una declaración sobre qué URL representa la versión autorizada de una página. Revisa el valor final.

Convierte el tema de la barra final en una decisión deliberada

La opción trailingSlash de Astro tiene como valor predeterminado ignore. Las opciones always y never fuerzan una forma para rutas bajo demanda en producción, mientras que el valor predeterminado acepta cualquiera de las dos formas en desarrollo y en renderizado bajo demanda.

En la salida estática, el comportamiento de los archivos generados y del host también afecta el resultado. Elige una forma canónica, genera enlaces internos con esa misma forma y prueba cómo el host desplegado maneja ambos variantes. Cambiar solo la opción de Astro no garantiza que cada host estático aplique las redirecciones que esperas.

El objetivo es el acuerdo: los enlaces internos, las canonicals, las entradas del sitemap y las redirecciones deben apuntar todos a la misma forma de URL. Nuestro guía de SEO para desarrolladores cubre la disciplina más amplia de implementación detrás de esa decisión.

Instala la integración oficial de sitemap

Ejecuta npx astro add sitemap para instalar la integración oficial @astrojs/sitemap de Astro.

Según la documentación oficial del sitemap, la integración necesita la URL del sitio desplegado, empezando con http:// o https://. Sin site, no genera un sitemap.

Después de una compilación, Astro añade sitemap-index.xml y sitemap-0.xml al directorio de salida. El índice referencia los archivos de sitemap numerados. El límite predeterminado es de 45.000 entradas por archivo; a partir de ahí se crean más archivos numerados (45.000 es un umbral de división, no una recomendación para “fabricar” páginas).

Inspecciona varias entradas tras el despliegue. Revisa el protocolo, el hostname, las rutas, la convención de barra y si se colaron páginas privadas o utilitarias. También abre el índice del sitemap y sigue sus enlaces hijos. He visto sitemaps técnicamente válidos desplegados en rutas que nadie había probado.

Un sitemap ayuda al descubrimiento; no fuerza el indexado. Para el resto de ese proceso, consulta cómo funciona el indexado en Google.

La trampa de la “isla” de Astro es específicamente client:only

Las islands de Astro no son malas para SEO por defecto. Decir eso confunde la hidratación selectiva con el renderizado exclusivamente en el cliente.

La referencia de directivas de Astro dice que client:only “omite el renderizado en servidor de HTML y renderiza solo en el cliente”. Todo lo que haya dentro de ese componente no aparece en el HTML renderizado inicialmente en servidor y depende de la ejecución de JavaScript.

No pongas copias de artículos, descripciones de productos, respuestas de FAQ, navegación principal, enlaces internos ni otro contenido indexable dentro de client:only. Déjalo para interfaces que no pueden renderizar en el servidor y cuyo contenido no necesita aparecer en la respuesta inicial.

client:load, client:idle y client:visible son distintos. Renderizan el HTML inicial en servidor y luego controlan cuándo ocurre la hidratación. El problema no es React, Vue, Svelte o las islands en sí. El problema es saltarse el renderizado en servidor o traer contenido esencial solo al navegador.

Por lo que vemos en los sitios revisados con SEOJuice, el fallo revelador en builds basadas en frameworks de JavaScript a menudo no es un sitemap faltante. Es una página que se ve completa en el navegador mientras que su bloque de texto significativo no está en la respuesta HTML cruda. En Astro, un límite único de client:only es un primer lugar evidente para mirar, aunque la carga de datos solo del navegador también puede producir el mismo resultado.

Yo cometí este error al revisar únicamente la página renderizada. Más precisamente: revisé lo que reconstruyó el navegador, no lo que devolvió el servidor. Ver el código fuente de la respuesta habría terminado la investigación mucho antes. Es el mismo fallo tipo “app-shell” que se trata en nuestras mejores prácticas de SEO para aplicaciones de página única (SPA).

Usa salida estática salvo que el renderizado bajo demanda resuelva un problema real

“Por defecto, todo tu sitio Astro se pre-renderizará y se enviarán páginas HTML estáticas al navegador.”

Esto viene de la guía de renderizado bajo demanda de Astro. El modo predeterminado output: 'static' genera páginas en el momento de la compilación. Es la opción directa para documentación, artículos, landing pages y contenido de producto que no dependa de datos específicos de la solicitud.

output: 'server' renderiza bajo demanda y requiere un adaptador para el entorno objetivo, como Node, Netlify, Vercel o Cloudflare. El renderizado en servidor puede devolver HTML completo y no es intrínsecamente peor para SEO. Simplemente añade infraestructura en tiempo de ejecución, latencia y otra superficie de fallo. Úsalo porque la página lo necesita, no porque SSR suene “más capaz”.

Puedes mezclar ambos comportamientos. En modo estático, exporta prerender = false en una página que deba renderizarse bajo demanda. En modo servidor, exporta prerender = true para una página que deba generarse con antelación.

Tutoriales antiguos pueden recomendar output: 'hybrid'. Astro 5 unificó el comportamiento híbrido antiguo dentro de 'static'; la guía de actualización a Astro 5 describe 'hybrid' y 'static' como fusionados en una única configuración estática. Los proyectos actuales deberían usar static o server con overrides de prerender por página.

Añade RSS si el sitio publica contenido recurrente

Astro ofrece el paquete oficial @astrojs/rss para feeds generados mediante endpoints de API. Instálalo con npm install @astrojs/rss y luego crea un endpoint como src/pages/rss.xml.js que devuelva la ayuda (helper) de RSS con site: context.site y los elementos del feed.

La documentación de Astro RSS requiere un site configurado porque ese origen se usa para generar enlaces a artículos. Esta es otra razón para tratar site como configuración base y no como una opción específica del sitemap.

Inspecciona el sitio generado, no solo los componentes fuente

Los componentes de Astro pueden verse correctos mientras que el resultado desplegado esté mal. Compila y despliega, y luego verifica:

1. La respuesta HTML en bruto contiene el contenido principal y los enlaces importantes.
2. Toda página indexable tiene un título y una descripción meta adecuados.
3. La canonical es absoluta, usa HTTPS y apunta al hostname de producción.
4. Las canonicals, los enlaces internos, las redirecciones y las URLs del sitemap comparten una misma convención de barra.
5. Las imágenes de Open Graph y Twitter usan URLs absolutas de producción.
6. sitemap-index.xml existe y referencia sitemaps hijos accesibles.
7. No existe contenido indexable únicamente dentro de componentes client:only.
8. Las páginas que deben ser estáticas aparecen en la salida de compilación generada.
9. Los hosts de preview y staging no se emiten a sí mismos como canonicals.
10. Las redirecciones se comportan como esperas en la plataforma de hosting real.

Usa “ver código fuente”, solicita la URL sin depender de la ejecución en el navegador, y revisa los archivos desplegados. El panel Elements de DevTools muestra el DOM posterior a la ejecución: es útil, pero responde a una pregunta distinta (a mí todavía me pasa mirar primero el equivocado).

Astro gestiona bien la base del renderizado. El trabajo recurrente es mantener metadatos, enlaces internos, esquema y consistencia de página a medida que el sitio crece. SEOJuice puede ejecutarse sobre Astro mediante un snippet de JavaScript y aplicar continuamente correcciones en el sitio: enlaces internos, títulos y descripciones meta, marcado de schema y texto alternativo de imágenes. El free SEO audit también es una forma sin registro de inspeccionar metadatos y canonicals ya publicados.

No sustituye configurar site, generar un sitemap o mantener el contenido indexable en el HTML inicial. La automatización debería estar encima de una compilación correcta.

Preguntas frecuentes

¿Astro es bueno para SEO?

Sí. Astro pre-renderiza HTML estático y, por defecto, elimina el JavaScript del lado del cliente, así que el contenido puede estar presente en la respuesta inicial en lugar de depender de la fase de renderizado diferido de JavaScript de Google. El posicionamiento sigue dependiendo de contenido útil, metadatos, enlazado interno, canonicals y otras decisiones de implementación.

¿Cómo agrego títulos y descripciones meta en Astro?

Añade etiquetas estándar de title y descripción meta a un layout compartido, y luego pasa valores únicos mediante Astro.props para cada página. El paquete comunitario astro-seo es otra opción, pero no es una integración oficial de Astro.

¿Cómo agrego un sitemap a un sitio Astro?

Ejecuta npx astro add sitemap y configura site como la URL desplegada en astro.config.mjs. Luego, una compilación emite sitemap-index.xml y sitemap-0.xml. Sin la configuración de site, la integración no puede generar el sitemap.

¿Cómo configuro URLs canonical en Astro?

Usa el patrón documentado de Astro: crea una URL con new URL(Astro.url.pathname, Astro.site) y luego emite ese valor en una etiqueta link canonical. Configura site primero porque Astro.site de lo contrario será undefined.

¿Cuál es la diferencia entre la salida estática y SSR en Astro?

output: 'static' es el valor predeterminado y pre-renderiza páginas a HTML en tiempo de compilación. output: 'server' renderiza bajo demanda y requiere un adaptador. Puedes mezclar el comportamiento por página con prerender = false en modo estático o prerender = true en modo servidor.

¿Por qué mi sitemap o mi URL canonical en Astro no funciona?

Revisa primero site. Por defecto es undefined, mientras que la generación de sitemaps, Astro.site, la construcción de canonicals, los enlaces RSS a artículos y muchas URLs sociales absolutas dependen de ello. Configúralo como el origen final en HTTPS, vuelve a compilar y revisa la salida generada.