Solucionando Problemas

Astro providencia várias ferramentas diferentes para te ajudar a solucionar problemas e depurar o seu código.

Dicas e truques

Depuração com `console.log()`

console.log() é um método simples, mas popular, de depurar seu código Astro. O local onde você escreve sua instrução console.log() determinará onde sua saída de depuração é impressa:

---
console.log('Oi! Estou no servidor. Isso vai aparecer no terminal que o Astro está executando.');
---

<script>
console.log('Oi! Estou no navegador. Isso irá aparecer no console do seu browser.');
</script>

Uma instrução console.log() no frontmatter do Astro sempre produzirá saída no terminal em que a CLI do Astro está sendo executada. Isso ocorre porque o Astro é executado no servidor e nunca no navegador.

O código escrito ou importado dentro de uma tag <script> do Astro é executado no navegador. Qualquer instrução console.log() ou outra saída de depuração será impressa no console do seu navegador.

Depuração de componentes de framework

Componentes de framework (como React e Svelte) são únicos: eles são renderizados no lado do servidor por padrão, o que significa que a saída de depuração do console.log() será visível no terminal. No entanto, eles também podem ser hidratados para o navegador, o que pode fazer com que os logs de depuração também apareçam no navegador.

Isso pode ser útil para depurar diferenças entre a saída do SSR e os componentes hidratados no navegador.

Componente `<Debug />` do Astro

Para ajudar na depuração de seus componentes Astro, o Astro fornece um componente embutido <Debug /> que renderiza qualquer valor diretamente em seu modelo HTML de componente. Isso é útil para depuração rápida no navegador sem precisar alternar entre o terminal e o navegador.

---
import { Debug } from 'astro:components';
const soma = (a, b) => a + b;
---
<!-- Exemplo: Irá aparecer {resposta: 6} no navegador -->
<Debug resposta={soma(2, 4)} />

O componente de depuração suporta uma variedade de opções de sintaxe para depuração ainda mais flexível e concisa:

---
import { Debug } from 'astro:components';
const soma = (a, b) => a + b;
const resposta = soma(2, 4);
---
<!-- Exemplo: Todos os exemplos são equivalentes -->
<Debug resposta={soma(2, 4)} />
<Debug {{resposta: soma(2, 4)}} />
<Debug {resposta} />

Mensagens de Erro Comuns

Aqui estão algumas mensagens de erro comuns que você pode encontrar no terminal, o que elas significam e o que fazer sobre elas. Consulte nosso guia de referência de erros completo para uma lista completa de erros do Astro que você pode encontrar.

Cannot use import statement outside a module

Em componentes Astro, tags <script> são movidas para o topo do escopo (hoisted) e carregadas como módulos JS por padrão. Se você incluiu a diretiva is:inline ou qualquer outro atributo em sua tag, esse comportamento padrão é removido.

Solução: Se você adicionou qualquer atributo a sua tag <script>, você também deve adicionar o atributo type="module" para ser capaz de usar declarações de importação.

Status: Comportamento esperado do Astro, como pretendido.

Não tem certeza se este é o seu problema? Verifique nossas issues e veja se mais alguém reportou esse problema!

`document` (or `window`) is not defined

Esse erro ocorre ao tentar acessar document ou window no servidor.

Componentes Astro são executados no servidor, então você não pode acessar esses objetos específicos do navegador dentro do frontmatter.

Componentes de frameworks são executados no servidor por padrão, então esse erro pode ocorrer ao acessar document ou window durante a renderização.

Solução: Determine o código que chama document ou window. Se você não estiver utilizando document ou window diretamente e ainda está recebendo esse erro, verifique para ver se algum pacote que você está importando foi feito para ser executado no cliente.

Se o código está em um componente Astro, mova-o para uma tag <script> fora do frontmatter. Isso diz ao Astro para executar esse código no cliente, onde document e window estão disponíveis.
Se o código está em um componente de framework, tente acessar esses objetos após renderizar usando métodos de lifecycle (e.x. useEffect() no React, onMounted() no Vue e onMount() no Svelte). Você também pode prevenir o componente de ser renderizado no servidor ao adicionar a diretiva client:only.

Status: Comportamento esperado do Astro, como pretendido.

Expected a default export

Este erro pode ser lançado ao tentar importar ou renderizar um componente inválido, ou um que não está funcionando corretamente. (Esta mensagem em particular ocorre por causa da forma em que importar um componente de UI funciona no Astro.)

Solução: Tente procurar erros em quaisquer componentes que você está importando e renderizando, e certifique-se que estão funcionando corretamente. Considere abrir um dos templates iniciais do Astro em astro.new e tente solucionar o problema do seu componente em um projeto Astro mínimo.

Status: Comportamento esperado do Astro, como pretendido.

Refused to execute inline script

Você pode ver o seguinte erro no log do console do navegador:

Refused to execute inline script because it violates the following Content Security Policy directive: …

Isso significa que a Política de Segurança de Conteúdo (CSP) do seu site desativou a execução de tags <script> inline, que o Astro gera por padrão.

Solução: Atualize sua CSP para incluir script-src: 'unsafe-inline' para permitir que scripts inline sejam executados.

Pegadinhas comuns

Meu componente não está sendo renderizado

Primeiro, certifique-se de que você importou o componente no script do seu componente .astro ou no arquivo .mdx.

Então verifique sua declaração de importação:

Estaria a sua importação vinculada ao lugar errado? (Verifique o caminho da importação.)
Sua importação tem o mesmo nome que o componente importado? (Verifique o nome do seu componente e se ele segue a sintaxe do .astro.)
Você incluiu a extensão na importação? (Verifique se seu arquivo importado contém uma extensão. e.x. .astro, .md, .jsx, .vue, .svelte. Nota: Extensões de arquivo não são necessárias apenas para arquivos .js(x) e .ts(x).)

Meu componente não é interativo

Se o seu componente está sendo renderizado (veja acima) mas não está respondendo a interação do usuário, então você pode está esquecendo de uma diretiva client:* para hidratar seu componente.

Por padrão, um componente de framework de UI não é hidratado no cliente. Se nenhuma diretiva client:* é providenciada, seu HTML é renderizado na página sem JavaScript.

Cannot find package ‘X’

Se você encontrar um aviso "Cannot find package 'react'" (ou similar) ao iniciar o Astro, isso significa que você precisa instalar aquele pacote em seu projeto. Nem todos os gerenciadores de pacotes irão instalar as dependências de pares para você automaticamente. Se você estiver no Node v16+ e está utilizando npm, você não deve se preocupar com esta seção.

React, por exemplo, é uma dependência de pares da integração @astrojs/react. Isso significa que você deve instalar os pacotes oficiais react e react-dom juntos da integração. Essa integração irá então utilizar esses pacotes automaticamente.

# Exemplo: Instale integrações e frameworks juntos
npm install @astrojs/react react react-dom

Veja o guia de integrações do Astro para instruções em como adicionar renderers de frameworks, ferramentas de CSS e outros pacotes no Astro.

`Astro.glob()` - no matches found

Quando estiver utilizando Astro.glob para importar arquivos, certifique-se de que você utilizou a sintaxe de glob correta que irá encontrar todos os arquivos que você precisa.

Caminhos de arquivo

Por exemplo, utilize ../components/**/*.js em src/pages/index.astro para importar ambos os arquivos a seguir:

src/components/MeuComponente.js
src/components/inclui/MeuOutroComponente.js

Valores Suportados

Astro.glob() não suporta variáveis dinâmicas e interpolação de strings.

Isto não é um bug no Astro. Isso acontece por conta de uma limitação na função import.meta.glob() do Vite que apenas suporta string literals estáticas.

Uma solução comum é no lugar importar um largo conjunto de arquivos que inclui todos os arquivos que você precisa utilizando Astro.glob() e então os filtrar:

---
const { slugPostagem } = Astro.props;
const caminhoParaPostagemDestacada = `src/pages/blog/${slugPostagem}.md`;

const postagens = await Astro.glob('../pages/blog/*.md');
const minhaPostagemDestacada = postagens.find(post => post.file.includes(caminhoParaPostagemDestacada));
---

<p>
  Dê uma olhada na minha postagem favorita, <a href={minhaPostagemDestacada.url}>{minhaPostagemDestacada.frontmatter.titulo}</a>!
</p>

Utilizando Astro com Yarn 2+ (Berry)

Yarn 2+, também conhecido como Berry, utiliza uma técnica chamada Plug’n’Play (PnP) para armazenar e gerenciar módulos Node e que pode causar problemas durante a inicialização de um novo projeto Astro utilizando create astro ou enquanto você trabalha com Astro. Uma solução para este problema é definir a propriedade nodeLinker em .yarnrc.yml para node-modules:

nodeLinker: "node-modules"

Adicionando dependências ao Astro em um monorepo

Quando trabalhando com Astro em uma configuração monorepo, as dependências do projeto devem ser adicionadas no arquivo package.json de cada um dos projetos.

Entretanto, você pode também querer usar o Astro na raiz do monorepo (ex. projetos Nx recomendam instalar dependências na raiz). Nesse caso, adicione manualmente as dependências relacionadas ao Astro (ex. @astrojs/vue, astro-component-lib) para a parte vite.ssr.noExternal da configuração do Astro para garantir que essas dependências sejam apropriadamente instaladas e empacotadas:

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

Utilizando `<head>` em um componente

No Astro, utilizar uma tag <head> funciona como qualquer outra tag HTML: ela não é movida para o topo da página ou combinada com a <head> existente. Por causa disso, você geralmente apenas quer incluir uma tag <head> pela a página. Nós recomendamos escrever aquela única <head> e seus conteúdos em um componente de layout.

Um `<script>` ou `<style>` inesperado foi incluído

Você pode notar as tags <script> ou <style> de um componente importado no seu código-fonte HTML mesmo que o componente não apareça no resultado final. Por exemplo, isso irá ocorrer com componentes renderizados condicionalmente que não são mostrados.

O processo de build do Astro trabalha no gráfico de módulos: assim que um componente é incluído no template, suas tags <script> e <style> são processadas, otimizadas e passam por bundle, independente de aparecer no resultado final ou não. Isso não se aplica a scripts quando a diretiva is:inline é aplicada.

Criando reproduções mínimas

Enquanto estiver procurando a solução de problemas em seu código, pode ser útil criar uma reprodução mínima do problema que você possa compartilhar. Isto seria um projeto Astro menor e simplificado que demonstra seu problema. Tendo uma reprodução funcional em um novo projeto ajuda a confirmar que este é um problema repetível, e não é causado por outra coisa em seu ambiente pessoal ou projeto existente.

Compartilhar uma reprodução mínima é útil quando estiver pedindo por ajuda em nossas threads de suporte e é muitas vezes obrigatória quando estiver registrando um relatório de bug para o Astro.

Crie um StackBlitz pelo astro.new

Você pode usar astro.new para criar um novo projeto Astro em um único clique. Para reproduções mínimas, nós recomendamos fortemente começar a partir do exemplo mínimo (vazio) rodando no StackBlitz, com o mínimo de código extra possível.

StackBlitz vai rodar esse projeto Astro no navegador, fora do seu ambiente local. Ele também vai te fornecer um link compartilhável para que qualquer mantenedor do Astro ou membro da equipe de suporte possa ver a sua reprodução mínima fora de seus próprios ambientes locais. Isso significa que todos estão vendo exatamente o mesmo projeto, com as mesmas configurações e dependências. Isso torna fácil para alguém ajudar a resolver os problemas em seu código. Se o problema é reproduzível, isso permite que você verifique que o problema está dentro do próprio código do Astro e você pode se sentir confiante enviando um relatório de bug.

Note que nem todos os problemas são reproduzíveis no StackBlitz. Por exemplo, seu problema pode ser dependente de um ambiente específico, ou gerenciador de pacotes, ou pode envolver streaming de HTML, que não é suportado no StackBlitz. Nesse caso, crie um projeto Astro mínimo (vazio) usando o CLI, reproduza o problema, e envie o projeto para um repositório do GitHub. Ao invés de compartilhar a URL do StackBlitz, forneça o link para o repositório GitHub da sua reprodução mínima.

Código mínimo

Uma vez que seu projeto vazio esteja configurado, prossiga com os passos para reproduzir seu problema. Isso pode incluir adicionar pacotes, mudar configurações e escrever código.

Você deve adicionar somente o mínimo de código necessário para reproduzir o problema. Não reproduza outros elementos do seu projeto existente, e remove todo o código que não é diretamente relacionado com o problema.

Crie uma issue

Se seu problema pode ser reproduzido, então é hora de criar uma issue e registrar um relatório de bug!

Vá para o repositório apropriado do Astro no GitHub e abre uma nova issue. A maioria dos repositórios possuem um modelo de issue que vai fazer perguntas ou solicitar informações para poder enviar. É importante que você siga esses modelos por que se você não providenciar as informações que nós precisamos, então teremos que pedir pra você por elas… e ninguém estará trabalhando na sua issue!

Inclua o link para a sua reprodução mínima no StackBlitz (ou repositório do GitHub, se necessário). Comece com uma descrição do que era esperado em comparação com o comportamento real para fornecer contexto para a issue. Depois, inclua claramente, instruções passo a passo de como replicar o problema em um projeto Astro.

Precisa de mais?

Venha e fale conosco no Discord e explique seu problema no canal #support. Nós estamos sempre felizes em ajudar!

Visite os atuais issues abertos no Astro para ver se você está enfrentando um problema conhecido ou para reportar um bug.

Você também pode visitar as Discussões de RFC para ver se você encontrou uma limitação conhecida do Astro, e verifique para ver se existem propostas atuais relacionadas ao seu caso de uso.

Criar uma Issue no GitHub

Enviar feedback

Solucionando Problemas

Dicas e truques

Depuração com `console.log()`

Depuração de componentes de framework

Componente `<Debug />` do Astro

Mensagens de Erro Comuns

Cannot use import statement outside a module

`document` (or `window`) is not defined

Expected a default export

Refused to execute inline script

Pegadinhas comuns

Meu componente não está sendo renderizado

Meu componente não é interativo

Cannot find package ‘X’

`Astro.glob()` - no matches found

Caminhos de arquivo

Valores Suportados

Utilizando Astro com Yarn 2+ (Berry)

Adicionando dependências ao Astro em um monorepo

Utilizando `<head>` em um componente

Um `<script>` ou `<style>` inesperado foi incluído

Criando reproduções mínimas

Crie um StackBlitz pelo astro.new

Código mínimo

Crie uma issue

Precisa de mais?

Solucionando Problemas

Dicas e truques

Depuração com console.log()

Depuração de componentes de framework

Componente <Debug /> do Astro

Mensagens de Erro Comuns

Cannot use import statement outside a module

document (or window) is not defined

Expected a default export

Refused to execute inline script

Pegadinhas comuns

Meu componente não está sendo renderizado

Meu componente não é interativo

Cannot find package ‘X’

Astro.glob() - no matches found

Caminhos de arquivo

Valores Suportados

Utilizando Astro com Yarn 2+ (Berry)

Adicionando dependências ao Astro em um monorepo

Utilizando <head> em um componente

Um <script> ou <style> inesperado foi incluído

Criando reproduções mínimas

Crie um StackBlitz pelo astro.new

Código mínimo

Crie uma issue

Precisa de mais?

Depuração com `console.log()`

Componente `<Debug />` do Astro

`document` (or `window`) is not defined

`Astro.glob()` - no matches found

Utilizando `<head>` em um componente

Um `<script>` ou `<style>` inesperado foi incluído