Resolución de problemas

Astro proporciona varias herramientas diferentes para ayudarte a solucionar problemas y depurar tu código.

Consejos y trucos

Depurar con console.log()

console.log() es un método simple pero popular para depurar tu código de Astro. Dónde escribas tu statement console.log() determinará dónde se imprime tu salida de depuración:

---
console.log('Hi! I’m the server. This is logged in the terminal where Astro is running.');
---

<script>
console.log('Hi! I’m the client. This is logged in browser dev console.');
</script>

Un statement console.log() en el frontmatter de Astro siempre mostrará su salida en la terminal que ejecuta el CLI de Astro. Esto se debe a que Astro se ejecuta en el servidor, y nunca en el navegador.

El código escrito o importado dentro de una etiqueta <script> de Astro se ejecuta en el navegador. Cualquier statement console.log() u otra salida de depuración se imprimirá en la consola de tu navegador.

Depurar componentes de framework

Los componentes de framework (como React y Svelte) son únicos: se renderizan en el servidor por defecto, lo que significa que la salida de depuración de console.log() será visible en la terminal. Sin embargo, también pueden hidratarse para el navegador, lo que puede hacer que tus logs de depuración también aparezcan en el navegador.

Esto puede ser útil para depurar diferencias entre la salida del servidor y los componentes hidratados en el navegador.

Componente <Debug /> de Astro

Para ayudarte a depurar tus componentes de Astro, Astro proporciona un componente integrado <Debug /> que renderiza cualquier valor directamente en la plantilla HTML de tu componente.

Este componente proporciona una forma de inspeccionar valores en el lado del cliente, sin ningún JavaScript. Puede ser útil para depuración rápida en el navegador sin tener que alternar entre tu terminal y tu navegador.

---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
---

<!-- Example: Outputs {answer: 6} to the browser -->
<Debug answer={sum(2, 4)} />

El componente Debug soporta una variedad de opciones de sintaxis para una depuración aún más flexible y concisa:

---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Example: All three examples are equivalent. -->
<Debug answer={sum(2, 4)} />
<Debug {...{answer: sum(2, 4)}} />
<Debug {answer} />

Mensajes de error comunes

Aquí hay algunos mensajes de error comunes que puedes ver en la terminal, lo que podrían significar, y qué hacer al respecto. Consulta nuestra guía de referencia completa de errores para una lista completa de errores de Astro que podrías encontrar.

No se puede usar import statement fuera de un módulo

En los componentes de Astro, las etiquetas <script> se cargan como módulos JS por defecto. Si has incluido la directiva is:inline o cualquier otro atributo en tu etiqueta, este comportamiento por defecto se elimina.

Solución: Si has añadido cualquier atributo a tu etiqueta <script>, también debes añadir el atributo type="module" para poder usar import statements.

Estado: Comportamiento esperado de Astro, según lo previsto.

¿No estás seguro de que este sea tu problema?
¡Revisa si alguien más ha reportado este problema!

document (o window) no está definido

Este error ocurre al intentar acceder a document o window en el servidor.

Los componentes de Astro se ejecutan en el servidor, por lo que no puedes acceder a estos objetos específicos del navegador dentro del frontmatter.

Los componentes de framework se ejecutan en el servidor por defecto, por lo que este error puede ocurrir al acceder a document o window durante el renderizado.

Solución: Determina el código que llama a document o window. Si no estás usando document o window directamente y sigues recibiendo este error, revisa si alguno de los paquetes que estás importando está diseñado para ejecutarse en el cliente.

• Si el código está en un componente de Astro, muévelo a una etiqueta <script> fuera del frontmatter. Esto le dice a Astro que ejecute este código en el cliente, donde document y window están disponibles.

• Si el código está en un componente de framework, intenta acceder a estos objetos después del renderizado usando métodos de lifecycle (p. ej. useEffect() en React, onMounted() en Vue, y onMount() en Svelte). Indica al componente de framework que se hidrate en el lado del cliente usando una directiva client:, como client:load, para ejecutar estos métodos de lifecycle. También puedes evitar que el componente se renderice en el servidor añadiendo la directiva client:only.

Estado: Comportamiento esperado de Astro, según lo previsto.

Se esperaba un default export

Este error puede lanzarse al intentar importar o renderizar un componente no válido, o uno que no funciona correctamente. (Este mensaje en particular ocurre por la forma en que funciona la importación de un componente de UI en Astro.)

Solución: Intenta buscar errores en cualquier componente que estés importando y renderizando, y asegúrate de que funciona correctamente. Considera abrir una plantilla de inicio de Astro desde astro.new y solucionar problemas solo de tu componente en un proyecto mínimo de Astro.

Estado: Comportamiento esperado de Astro, según lo previsto.

Se rechazó ejecutar script inline

Puedes ver el siguiente error registrado en la consola del navegador:

Se rechazó ejecutar el script inline porque viola la siguiente directiva de Content Security Policy: …

Esto significa que el Content Security Policy (CSP) de tu sitio no permite ejecutar etiquetas <script> inline, que Astro genera por defecto.

Solución: Actualiza tu CSP para incluir script-src: 'unsafe-inline' para permitir que los scripts inline se ejecuten. Alternativamente, puedes usar una integración de terceros como astro-shield para generar los headers CSP por ti.

Problemas comunes

Mi componente no se renderiza

Primero, verifica que has importado el componente en tu script de componente .astro o archivo .mdx.

Luego revisa tu import statement:

• ¿Tu import apunta al lugar equivocado? (Revisa tu import path.)

• ¿Tu import tiene el mismo nombre que el componente importado? (Revisa el nombre de tu componente y que siga la sintaxis de .astro.)

• ¿Has incluido la extensión en la importación? (Verifica que tu archivo importado contiene una extensión. P. ej. .astro, .md, .vue, .svelte. Nota: Las extensiones de archivo no son obligatorias solo para archivos .js(x) y .ts(x).)

Mi componente no es interactivo

Si tu componente se está renderizando (ver arriba) pero no responde a la interacción del usuario, puede que te falte una directiva client:* para hidratar tu componente.

Por defecto, un componente de UI Framework no se hidrata en el cliente. Si no se proporciona ninguna directiva client:*, su HTML se renderiza en la página sin JavaScript.

Consejo

Los componentes de Astro son componentes de plantilla solo de HTML sin tiempo de ejecución del lado del cliente. Pero puedes usar una etiqueta <script> en la plantilla de tu componente de Astro para enviar JavaScript al navegador que se ejecute en el ámbito global.

No se puede encontrar el paquete ‘X’

Si ves una advertencia "Cannot find package 'react'" (o similar) al iniciar Astro, significa que necesitas instalar ese paquete en tu proyecto. No todos los gestores de paquetes instalarán las peer dependencies automáticamente. Si estás en Node v16+ y usas npm, no deberías preocuparte por esta sección.

React, por ejemplo, es una peer dependency de la integración @astrojs/react. Esto significa que debes instalar los paquetes oficiales react y react-dom junto con tu integración. La integración luego extraerá de estos paquetes automáticamente.

# Example: Install integrations and frameworks together
npm install @astrojs/react react react-dom

Consulta la guía de integración de Astro para instrucciones sobre cómo añadir renderizadores de framework, herramientas CSS y otros paquetes a Astro.

Usar Astro con Yarn 2+ (Berry)

Yarn 2+, también conocido como Berry, usa una técnica llamada Plug’n’Play (PnP) para almacenar y gestionar módulos de Node, lo que puede causar problemas al inicializar un nuevo proyecto de Astro usando create astro o al trabajar con Astro. Una solución alternativa es establecer la propiedad nodeLinker en .yarnrc.yml a node-modules:

.yarnrc.yml

nodeLinker: "node-modules"

Añadir dependencias a Astro en un monorepo

Al trabajar con Astro en una configuración de monorepo, las dependencias del proyecto deben añadirse en el archivo package.json de cada proyecto.

Sin embargo, también puedes querer usar Astro en la raíz del monorepo (p. ej. los proyectos Nx recomiendan instalar dependencias en la raíz). En este caso, añade manualmente las dependencias relacionadas con Astro (p. ej. @astrojs/vue, astro-component-lib) a la parte vite.ssr.noExternal de la configuración de Astro para asegurar que estas dependencias se instalen y empaqueten correctamente:

astro.config.mjs

import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})

Usar <head> en un componente

En Astro, usar una etiqueta <head> funciona como cualquier otra etiqueta HTML: no se mueve a la parte superior de la página ni se fusiona con el <head> existente. Por esto, normalmente solo querrás incluir una etiqueta <head> en toda una página. Recomendamos escribir ese único <head> y sus contenidos en un componente layout.

Se incluye un <style> inesperado

Puedes notar que la etiqueta <style> de un componente importado se incluye en tu código fuente HTML incluso si ese componente no aparece en la salida final. Por ejemplo, esto ocurrirá con componentes renderizados condicionalmente que no se muestran.

El proceso de build de Astro funciona sobre el grafo de módulos: una vez que un componente se incluye en la plantilla, su etiqueta <style> se procesa, optimiza, y empaqueta, independientemente de si aparece en la salida final o no.

Escapar caracteres especiales en Markdown

Ciertos caracteres tienen un significado especial en Markdown. Puede que necesites usar una sintaxis diferente si quieres mostrarlos. Para hacerlo, puedes usar entidades HTML para estos caracteres en su lugar.

Por ejemplo, para evitar que < se interprete como el inicio de un elemento HTML, escribe <.

Crear reproducciones mínimas

Al solucionar problemas de tu código, puede ser útil crear una reproducción mínima del problema que puedas compartir. Este es un proyecto de Astro más pequeño y simplificado que demuestra tu problema. Tener una reproducción funcional en un nuevo proyecto ayuda a confirmar que este es un problema repetible, y no está causado por algo más en tu entorno personal o proyecto existente.

Compartir una reproducción mínima es útil al pedir ayuda en nuestros hilos de soporte y a menudo es necesario al reportar un bug a Astro.

Crear un StackBlitz vía astro.new

Puedes usar astro.new para crear un nuevo proyecto de Astro con un solo clic. Para reproducciones mínimas, recomendamos encarecidamente empezar desde el ejemplo mínimo (vacío) ejecutándose en StackBlitz, con la menor cantidad de código extra posible.

StackBlitz ejecutará este proyecto de Astro en el navegador, fuera de tu entorno local. También te proporcionará un enlace compartible para que cualquier mantenedor de Astro o miembro del equipo de soporte pueda ver tu reproducción mínima fuera de su propio entorno local. Esto significa que todos están viendo exactamente el mismo proyecto, con la misma configuración y dependencias. Esto hace fácil que alguien más te ayude a solucionar problemas de tu código. Si el problema es reproducible, te permite verificar que el problema está dentro del código de Astro mismo y puedes sentirte confiado al enviar un reporte de bug.

Ten en cuenta que no todos los problemas son reproducibles en StackBlitz. Por ejemplo, tu problema puede depender de un entorno específico o gestor de paquetes, o puede involucrar HTML Streaming, que no es compatible con StackBlitz. En este caso, crea un nuevo proyecto de Astro mínimo (vacío) usando el CLI, reproduce el problema, y súbelo a un repositorio de GitHub. En lugar de compartir una URL de StackBlitz, proporciona un enlace al repositorio de GitHub de tu reproducción mínima.

Código mínimo

Una vez que tu proyecto vacío esté configurado, sigue los pasos para reproducir el problema. Esto puede incluir añadir paquetes, cambiar configuración, y escribir código.

Solo deberías añadir la cantidad mínima de código necesaria para reproducir el problema. No reproduzcas otros elementos de tu proyecto existente, y elimina todo el código que no esté directamente relacionado con el problema.

Crear un issue

Si tu problema puede reproducirse, ¡es momento de crear un issue y enviar un reporte de bug!

Ve al repositorio apropiado de Astro en GitHub y abre un nuevo issue. La mayoría de repositorios tienen una plantilla de issue que hará preguntas o requerirá información para poder enviarlo. Es importante que sigas estas plantillas porque si no proporcionas la información que necesitamos, entonces tenemos que pedírtela… ¡y nadie está trabajando en tu issue!

Incluye el enlace a tu reproducción mínima en StackBlitz (o repositorio de GitHub, si es necesario). Comienza con una descripción del comportamiento esperado versus el actual para proporcionar contexto del problema. Luego, incluye instrucciones claras, paso a paso, sobre cómo replicar el problema en un proyecto de Astro.

¿Necesitas más?

Ven a chatear con nosotros en Discord y explica tu problema en el canal del foro #support. ¡Siempre estamos felices de ayudar!

Visita los Issues abiertos actuales en Astro para ver si estás encontrando un problema conocido o para enviar un reporte de bug.

También puedes visitar Roadmap Discussions para ver si has encontrado una limitación conocida de Astro, y revisar si hay propuestas actuales relacionadas con tu caso de uso.