Como corrigir uma tela branca no seu app web

Uma tela branca quase sempre significa uma destas duas coisas: o JavaScript do app quebrou antes de desenhar qualquer coisa, ou o JavaScript nunca carregou. Abra o console do navegador (clique com o botão direito → Inspecionar → Console), leia o primeiro erro em vermelho e depois verifique a aba Rede em busca de arquivos que falharam ao carregar. A maioria das causas é uma variável de ambiente ausente, um caminho base errado, um build que não terminou ou um erro em um componente.

Este guia cobre apps de página única construídos com React, Vue ou frameworks semelhantes (inclusive apps criados por criadores com IA), que é onde as telas em branco são mais comuns.

Por que a página fica branca

Um app moderno de página única (SPA) envia ao navegador um arquivo HTML praticamente vazio, mais ou menos assim:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Em seguida, o JavaScript monta a página inteira dentro dessa div vazia. Se o script não carregar, ou gerar um erro antes de renderizar, a div continua vazia e você vê branco. A página não está “quebrada” de forma visível; ela simplesmente nunca foi desenhada.

Por isso a correção sempre começa nas ferramentas de desenvolvedor, e não na própria página.

Passo 1: leia o console

Abra as ferramentas de desenvolvedor: clique com o botão direito na página e escolha Inspecionar, ou pressione F12 (Cmd+Option+I no Mac). Vá para a aba Console e recarregue a página.

Olhe o primeiro erro em vermelho; os seguintes costumam ser efeitos colaterais. O que ele diz aponta para a causa:

Copie o texto completo do erro, incluindo o nome do arquivo e o número da linha. Se você usa um criador com IA, cole isso direto no chat.

Passo 2: verifique se os arquivos carregaram

Abra a aba Rede, marque Desativar cache e recarregue a página. Olhe as requisições para arquivos .js e .css.

• Status 404 em um arquivo JavaScript: a página está pedindo um arquivo que não existe no servidor.
• Status 200, mas o tipo é text/html: o servidor retornou uma página (muitas vezes o próprio index.html, por causa de um fallback de SPA) em vez do script. A causa raiz é a mesma: o arquivo não está onde a página espera.

Motivos comuns:

Caminho base errado. Se o app é servido a partir de uma subpasta, como exemplo.com/app/, mas foi compilado para carregar arquivos de /assets/..., todas as requisições de script falham. No Vite, isso é a opção base no vite.config; no Create React App, é o campo homepage; no Next.js, é o basePath. Ele precisa corresponder ao local onde o app está realmente servido.

index.html desatualizado. Ferramentas de build dão aos arquivos nomes com um hash do conteúdo, como index-a1b2c3.js. Depois de uma nova publicação, o arquivo antigo some. Se um navegador ou CDN ainda tem o index.html antigo em cache, ele pede o arquivo antigo e não recebe nada. Uma atualização forçada (Cmd+Shift+R ou Ctrl+Shift+R) confirma isso. A solução de longo prazo é servir o index.html com um cabeçalho de cache curto ou sem cache, enquanto os arquivos com hash ficam em cache por muito tempo.

O build não terminou ou não foi publicado. Se o build falhou, a hospedagem pode estar servindo uma pasta de saída antiga ou vazia. Verifique o log do build em busca de erros.

A pasta errada está publicada. A hospedagem precisa servir a saída do build (geralmente dist ou build), não a pasta de código-fonte do projeto. Servir o código-fonte resulta em um index.html que aponta para /src/main.tsx, que os navegadores não conseguem executar.

Passo 3: verifique as variáveis de ambiente

Apps de frontend costumam ler configurações como a URL de uma API ou uma chave pública no momento do build. Se uma variável está ausente na versão no ar, código como createClient(undefined, undefined) gera um erro imediatamente, e a página fica branca.

Coisas que você precisa saber:

• No Vite, apenas variáveis com o prefixo VITE_ estão disponíveis no código do navegador, lidas como import.meta.env.VITE_NOME. No Create React App, o prefixo é REACT_APP_; no Next.js, NEXT_PUBLIC_.
• Esses valores são gravados no app quando ele é compilado. Adicionar uma variável depois do build não faz efeito até você recompilar e publicar de novo.
• A prévia ou a sua máquina local pode ter um arquivo .env que o build de produção não tem. Defina as mesmas variáveis na hospedagem.
• Tudo com esses prefixos acaba no JavaScript público. Coloque ali apenas valores públicos, nunca chaves secretas.

Um teste rápido: procure no erro do console um undefined próximo ao nome de uma configuração, ou pergunte:

O app publicado mostra uma tela em branco. Liste todas as variáveis de ambiente que o frontend lê, verifique quais estão ausentes ou vazias no build ao vivo e faça o app mostrar uma mensagem de erro clara em vez de uma tela em branco quando alguma estiver faltando.

Passo 4: corrija a falha

Se o console mostra um erro normal de JavaScript, o código quebrou durante a renderização. Causas típicas em apps criados com IA:

• Dados ainda não carregados. Um componente lê user.name antes de user chegar. A correção é um estado de carregamento ou o encadeamento opcional (user?.name).
• Dados vazios. Uma conta nova não tem registros, e o código assume que a lista tem pelo menos um item.
• Formato de dado inesperado. Uma API retornou um objeto de erro no lugar da lista que o código esperava.
• Um import ausente depois que um arquivo foi renomeado ou movido.
• Usar uma API exclusiva do navegador durante a renderização no servidor, como window ou localStorage em um componente de servidor do Next.js.

Dê à IA o erro completo, a página e com qual conta você estava logado:

A página Dashboard fica em branco para usuários novos. Console: TypeError: Cannot read properties of undefined (reading 'map') em ProjectList.tsx:18. Funciona para a minha conta, que tem projetos. Corrija para que uma conta vazia mostre “Nenhum projeto ainda” e teste uma conta nova na prévia.

Passo 5: adicione um error boundary

No React, um único componente que quebra pode desmontar o app inteiro, e por isso um bug pequeno produz uma página completamente em branco. Um error boundary é um componente que captura erros de renderização abaixo dele e mostra um fallback.

Adicione um error boundary em volta das rotas principais que mostre “Algo deu errado” com um botão Recarregar, e registre o erro no console. Mantenha o cabeçalho e a navegação fora dele para que continuem sendo exibidos.

Ele não corrige o bug, mas o visitante vê uma mensagem em vez de uma tela vazia, e você descobre onde o erro aconteceu.

Passo 6: sem erros, mas ainda em branco

Se o console está limpo e os scripts carregam:

• Verifique a aba Elements. Há conteúdo dentro de <div id="root">? Se sim, está renderizando, mas invisível: texto branco sobre fundo branco, opacity: 0, display: none, ou um elemento em tela cheia cobrindo tudo.
• Verifique o roteador. Se nenhuma rota corresponde à URL atual e não há uma rota de “não encontrado”, alguns roteadores não renderizam nada. Adicione uma rota curinga que mostre uma página 404.
• Verifique o ponto de montagem. O código precisa montar em um elemento que existe. Se o index.html tem id="app" e o código procura root, nada aparece (e o React normalmente registra um erro).
• Verifique uma extensão do navegador. Tente uma janela privada. Bloqueadores de anúncios às vezes bloqueiam scripts com nomes como analytics ou ads.

Em branco só depois de atualizar uma página?

Se a página inicial funciona, mas atualizar /dashboard mostra uma tela em branco ou um 404, o servidor não sabe que deve enviar index.html para as rotas do app. É um problema de fallback de roteamento, coberto em como corrigir erros 404 depois de publicar.

Erros comuns

• Ler o último erro em vez do primeiro. A primeira linha em vermelho geralmente é a causa.
• Definir variáveis de ambiente sem recompilar. Variáveis do frontend são fixas no momento do build.
• Testar apenas com a sua própria conta. Falhas em contas vazias são uma das causas mais comuns de tela em branco.
• Presumir que a publicação funcionou. Verifique o log do build antes de depurar o código.
• Culpar o cache do navegador por tudo. Uma atualização forçada descarta isso em segundos; se a página continua em branco, é outra coisa.

Telas em branco na Mythex

Se a Prévia está em branco, primeiro confirme que o app está rodando (abra Código → terminal); depois peça à Mythex para iniciar o servidor correto, clique em Atualizar na barra de ferramentas da prévia, ou use /fix. Para uma URL publicada em branco, a documentação sugere aguardar um minuto e fazer uma atualização forçada, confirmar que as variáveis de ambiente e o banco de dados foram configurados antes de publicar e verificar a sua cota de hospedagem. Lembre-se de que um app publicado é um retrato: depois de corrigir algo, publique de novo. Se uma mudança causou o problema, Reverter para este ponto na última resposta boa volta o projeto atrás. Veja Solução de problemas e Solução de problemas de publicação na documentação, e nosso guia geral sobre como depurar um app criado com IA.

Checklist da tela em branco

• Li o primeiro erro em vermelho no Console
• Verifiquei na aba Rede os arquivos .js/.css que dão 404 ou retornam HTML
• O caminho base corresponde ao local onde o app é servido
• O build terminou, e a pasta de saída do build é a que está publicada
• Todas as variáveis de ambiente do frontend estão definidas na versão ao vivo, e recompilei
• Corrigi a falha, inclusive para contas novas e vazias
• Há um error boundary para que falhas futuras mostrem uma mensagem
• Há uma rota curinga para URLs desconhecidas
• Testei depois de uma atualização forçada e em uma janela privada

Perguntas