Um site publicado pode estar em branco mesmo que a pré-visualização no editor funcione. Essa diferença é útil: aponta primeiro para o ambiente de produção, ativos compilados ou roteamento em tempo real — e não para um redesign aleatório.
Resposta em 30 segundos
Abra a URL publicada, abra as ferramentas de desenvolvedor do navegador e recarregue uma vez. Use o primeiro erro vermelho do Console e a primeira solicitação de Rede falhada para escolher a ramificação:
- variável de ambiente está faltando ou
undefined→ adicione-a ao host de implantação e reimplante - JavaScript ou CSS retorna 404 → corrija a saída da build ou o caminho base público
Unexpected token <ou erro de MIME de módulo → a URL retornou uma página HTML em vez de JavaScript- apenas uma URL aninhada falha após recarregar → adicione o fallback de SPA documentado pelo host
- JavaScript lança uma exceção antes do app montar → corrija primeiro essa exceção de tempo de execução
Ramificação 1 — As variáveis de ambiente de produção estão faltando
Segredos armazenados dentro de um construtor de aplicativo não existem automaticamente em todos os hosts externos. Compare os nomes das variáveis no projeto com as variáveis configuradas para o ambiente de produção exato. Não copie valores de segredo para chat ou screenshots.
Para um aplicativo Vite do lado do cliente, apenas as variáveis intencionalmente expostas com o prefixo público do framework estão disponíveis no código do navegador. Nunca exponha uma chave do servidor apenas para fazer a tela em branco desaparecer. Adicione ou corrija a variável na plataforma de implantação, depois crie uma nova implantação; alterar uma variável não reescreve uma build que já existe.
Ramificação 2 — Os ativos compilados estão faltando
No painel de Rede, selecione uma solicitação falhada de JavaScript ou CSS. Um 404 geralmente significa que a saída implantada e a URL do ativo gerado discordam. Unexpected token < muitas vezes significa que a URL do script retornou uma página de erro HTML. Um erro de MIME de módulo pode significar que arquivos de origem foram enviados em vez da saída compilada.
Execute uma build de produção limpa localmente:
npm run build
Implante o diretório que seu framework realmente gera, como dist/ para um projeto padrão Vite. Siga a configuração atual da saída da build da plataforma, em vez de adivinhar o nome de uma pasta. Se o aplicativo for servido sob um subcaminho, verifique o caminho base público do framework contra aquele URL real.
Ramificação 3 — Um rota aninhada falha ao recarregar
Se / funciona, mas /dashboard está em branco ou 404 após uma visita direta, o roteador do navegador e o host discordam. Configure o fallback de aplicativo de página única documentado pela plataforma de hospedagem para que os rotas do aplicativo retornem index.html. Não redirecione arquivos de ativo ou rotas de API para index.html; isso pode produzir o erro Unexpected token < descrito acima.
Teste tanto uma visita direta quanto um refresh em um rota aninhada depois de implantar a regra de reescrita.
Ramificação 4 — O aplicativo em tempo real lança um erro de tempo de execução
Comece com a primeira exceção, não com todas as mensagens abaixo dela. Exemplos comuns incluem ler uma propriedade de undefined, inicializar um cliente de API sem uma URL obrigatória, ou importar código que assume que uma característica do navegador está disponível.
Forneça ao agente a exceção exata, o arquivo e o número da linha. Peça que ele explique por que esse valor está faltando antes de editar. Corrija uma causa, recompile e reteste a URL publicada em uma janela privada.
Verifique a correção
Use uma nova implantação e confirme:
- a build da implantação foi concluída com sucesso
- o console da página publicada não tem exceções não capturadas na primeira carga
- as solicitações de JavaScript e CSS retornam respostas bem-sucedidas com o tipo de conteúdo esperado
/e um rota aninhada funcionam ambos em uma janela privada- a interação principal funciona, não apenas a primeiro quadro
Uma aba cacheada pode mostrar uma falha antiga. Use uma janela privada ou um reload forçado para a verificação final.
Se ainda não funcionar
Restaure a última implantação que funcionou, depois compare os nomes das variáveis de ambiente, o comando de build, o diretório de saída e as regras de roteamento com a implantação que falhou. Se o provedor relatar um incidente, pare de alterar o código e aguarde. Caso contrário, envie ao suporte oficial a URL da implantação, o primeiro erro do Console, a primeira solicitação de Rede falhada e o log da implantação — após remover segredos e dados pessoais.
Resumo para iniciantes
Quando a pré-visualização funciona, mas o site publicado está branco, o ambiente em tempo real é diferente. Verifique o primeiro erro vermelho do Console, certifique-se de que o host tem as variáveis necessárias, implante a saída compilada e teste um URL aninhado. Mude uma ramificação por vez, em vez de pedir à IA para reescrever a página.