Como Corrigir uma Página Branca em Branco na Sua App Web

Uma página em branco quase sempre significa uma de duas coisas: o JavaScript da app falhou antes de desenhar fosse o que fosse, ou o JavaScript nunca chegou a carregar. Abra a consola do navegador (clique com o botão direito → Inspecionar → Consola), leia o primeiro erro a vermelho e depois verifique o separador Rede para ver os ficheiros que não carregaram. A maioria das causas é uma variável de ambiente em falta, um caminho base errado, um build que não terminou ou uma falha num componente.

Este guia cobre aplicações de página única construídas com React, Vue ou frameworks semelhantes (incluindo apps criadas por construtores com IA), que é onde as páginas em branco são mais comuns.

Porque é que a página fica branca

Uma aplicação de página única (SPA) moderna envia ao navegador um ficheiro HTML quase vazio, mais ou menos assim:

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

Depois, o JavaScript constrói toda a página dentro desse div vazio. Se o script não carregar, ou gerar um erro antes de renderizar, o div continua vazio e vê-se branco. A página não está "partida" de forma visível; simplesmente nunca foi desenhada.

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

Passo 1: leia a consola

Abra as ferramentas de programador: clique com o botão direito na página e escolha Inspecionar, ou prima F12 (Cmd+Option+I num Mac). Vá ao separador Consola e recarregue a página.

Veja o primeiro erro a vermelho; os seguintes são muitas vezes efeitos secundários. O que ele diz aponta para a causa:

Copie o texto completo do erro, incluindo o nome do ficheiro e o número da linha. Se estiver a usar um construtor com IA, cole-o diretamente no chat.

Passo 2: verifique se os ficheiros carregaram

Abra o separador Rede, marque Desativar cache e recarregue. Veja os pedidos a ficheiros .js e .css.

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

Razões comuns:

Caminho base errado. Se a app for servida a partir de uma subpasta, como exemplo.com/app/, mas tiver sido compilada para carregar ficheiros a partir de /assets/..., todos os pedidos de script falham. No Vite, isto é a opção base no vite.config; no Create React App é o campo homepage; no Next.js é o basePath. Tem de corresponder ao sítio onde a app é realmente servida.

index.html desatualizado. As ferramentas de build dão aos ficheiros nomes com um hash de conteúdo, como index-a1b2c3.js. Depois de uma nova publicação, o ficheiro antigo desaparece. Se um navegador ou uma CDN ainda tiver o index.html antigo em cache, pede o ficheiro antigo e não recebe nada. Uma atualização forçada (Cmd+Shift+R ou Ctrl+Shift+R) confirma isto. A solução a longo prazo é servir o index.html com um cabeçalho de cache curto ou sem cache, enquanto os ficheiros com hash ficam em cache durante muito tempo.

O build não terminou ou não foi publicado. Se o build falhou, o alojamento pode estar a servir uma pasta de resultados antiga ou vazia. Verifique o registo do build para encontrar erros.

A pasta errada está publicada. O alojamento tem de servir o resultado do build (normalmente dist ou build), e não a pasta de código-fonte do projeto. Servir o código-fonte dá-lhe um index.html que aponta para /src/main.tsx, que os navegadores não conseguem executar.

Passo 3: verifique as variáveis de ambiente

As apps de frontend costumam ler definições como um URL de API ou uma chave pública no momento do build. Se uma variável estiver em falta no build em produção, código como createClient(undefined, undefined) gera um erro imediatamente, e a página fica em branco.

Coisas a saber:

• No Vite, só as 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 é REACT_APP_; no Next.js, NEXT_PUBLIC_.
• Estes valores são incorporados quando a app é compilada. Acrescentar uma variável depois do build não faz nada até voltar a compilar e a publicar.
• A pré-visualização ou a máquina local podem ter um ficheiro .env que o build de produção não tem. Defina as mesmas variáveis no alojamento.
• Tudo o que tenha estes prefixos acaba no JavaScript público. Coloque lá apenas valores públicos, nunca chaves secretas.

Um teste rápido: procure na mensagem de erro da consola undefined perto do nome de uma definição, ou pergunte:

A app publicada mostra uma página em branco. Liste cada variável de ambiente que o frontend lê, verifique quais estão em falta ou vazias no build em produção, e faça com que a app mostre uma mensagem de erro clara em vez de uma página em branco quando alguma estiver em falta.

Passo 4: corrija a falha

Se a consola mostrar um erro normal de JavaScript, o código falhou durante a renderização. Causas típicas em apps criadas com IA:

• Dados ainda não carregados. Um componente lê user.name antes de user ter chegado. A solução é um estado de carregamento, ou o encadeamento opcional (user?.name).
• Dados vazios. Uma conta nova não tem registos, e o código assume que a lista tem pelo menos um item.
• Forma de dados inesperada. Uma API devolveu um objeto de erro em vez da lista que o código esperava.
• Um import em falta depois de um ficheiro ter sido renomeado ou movido.
• Usar uma API exclusiva do navegador durante a renderização no servidor, como window ou localStorage num componente de servidor do Next.js.

Dê à IA o erro completo, a página e com que conta tinha sessão iniciada:

A página Painel está em branco para os novos utilizadores. Consola: 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 "Ainda não há projetos", e teste uma conta nova na pré-visualização.

Passo 5: adicione um error boundary

No React, um único componente que falha pode desmontar a app inteira, e é por isso que um pequeno erro produz uma página completamente em branco. Um error boundary é um componente que apanha erros de renderização abaixo dele e mostra uma alternativa.

Adicione um error boundary em volta das rotas principais que mostre "Algo correu mal" com um botão Recarregar, e registe o erro na consola. Mantenha o cabeçalho e a navegação fora dele para que continuem a ser renderizados.

Não corrige o erro, mas os visitantes veem uma mensagem em vez de um ecrã em branco, e você vê onde falhou.

Passo 6: sem erros, mas continua em branco

Se a consola estiver limpa e os scripts carregarem:

• Verifique o separador Elementos. Há conteúdo dentro de <div id="root">? Se sim, está a renderizar mas invisível: texto branco sobre branco, opacity: 0, display: none, ou um elemento de ecrã inteiro a cobri-lo.
• Verifique o router. Se nenhuma rota corresponder ao URL atual e não existir uma rota de "não encontrado", alguns routers não renderizam nada. Adicione uma rota catch-all que mostre uma página 404.
• Verifique o ponto de montagem. O código tem de montar num elemento que exista. Se o index.html tiver id="app" e o código procurar root, não aparece nada (e o React normalmente regista um erro).
• Verifique uma extensão do navegador. Experimente uma janela privada. Os bloqueadores de anúncios por 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 página em branco ou um 404, o servidor não sabe que deve enviar o index.html para as rotas da app. É um problema de fallback de encaminhamento, tratado em como corrigir erros 404 depois de publicar.

Erros comuns

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

Páginas em branco na Mythex

Se a Pré-visualização estiver em branco, verifique primeiro se a app está a correr (abra Código → terminal) e depois peça à Mythex para iniciar o servidor correto, clique em Atualizar na barra de ferramentas da pré-visualização, ou use /fix. Para um URL publicado em branco, a documentação sugere esperar um minuto e fazer uma atualização forçada, confirmar que as variáveis de ambiente e a base de dados foram configuradas antes de publicar, e verificar a sua quota de alojamento. Lembre-se de que uma app publicada é um instantâneo: depois de corrigir algo, publique de novo. Se foi uma alteração que causou o problema, Reverter para este ponto na última resposta boa reverte o projeto. Veja Resolução de problemas e Resolução de problemas de publicação na documentação, e o nosso guia geral sobre como depurar uma app criada com IA.

Lista de verificação da página em branco

• Leu o primeiro erro a vermelho na Consola
• Verificou no separador Rede os ficheiros .js/.css que dão 404 ou devolvem HTML
• O caminho base corresponde ao sítio onde a app é servida
• O build terminou, e a pasta de resultados do build é a que está publicada
• Todas as variáveis de ambiente do frontend definidas no build em produção, e depois recompilado
• Falha corrigida, incluindo para contas vazias e novas
• Error boundary no lugar para que futuras falhas mostrem uma mensagem
• Rota catch-all para URLs desconhecidos
• Testado após uma atualização forçada e numa janela privada

Perguntas