Como corrigir erros 404 depois de publicar seu site ou app

Se o seu app funciona localmente, mas as páginas retornam 404 depois de publicar, a causa mais comum é a falta de roteamento de aplicação de página única (SPA): o servidor procura um arquivo chamado /dashboard que não existe, porque essa rota só existe no JavaScript. A correção é uma regra de fallback que serve index.html para as rotas do app. Outras causas são arquivos ausentes na saída do build, caminhos sensíveis a maiúsculas, diferenças na barra final, um caminho base incorreto e rotas de API que nunca foram publicadas.

Comece anotando exatamente qual URL dá 404 e como você chegou até ela. O padrão aponta diretamente para a causa.

Passo 1: identifique o padrão

O que você vê	Causa mais provável	Vá para
A página inicial funciona; clicar em links funciona; atualizar ou abrir um link direto dá 404	Falta o fallback de SPA	Passo 2
Todas as páginas dão 404, inclusive a inicial	Pasta errada publicada, ou o build não foi publicado	Passo 3
As páginas carregam, mas imagens, fontes ou scripts dão 404	Arquivos ausentes no build, ou caminhos errados	Passo 4
Funciona com `/sobre/`, falha com `/sobre` (ou o contrário)	Tratamento da barra final	Passo 5
`/Sobre` falha, mas `/sobre` funciona	Servidor sensível a maiúsculas	Passo 4
A página carrega, mas as chamadas de dados para `/api/...` dão 404	API não publicada ou sem roteamento	Passo 6
URLs antigas de um site anterior dão 404	Faltam redirecionamentos	Passo 7
Só em um domínio personalizado	Configuração de DNS ou de domínio	Passo 8

Para ver o status HTTP real, abra as ferramentas de desenvolvedor (clique com o botão direito → Inspecionar), vá para a aba Rede, recarregue a página e veja o status da primeira requisição.

Passo 2: adicione o fallback de SPA

Este é o caso clássico. Em um app de página única em React, Vue ou Svelte, o servidor tem apenas alguns arquivos reais: index.html e alguns arquivos JavaScript e CSS. Rotas como /dashboard ou /projetos/42 são tratadas por um roteador no navegador.

Clicar em um link funciona: o roteador muda a URL e desenha a nova página sem pedir nada ao servidor.
Atualizar ou abrir um link diretamente falha: o navegador pede ao servidor /dashboard, o servidor não tem esse arquivo e retorna 404.

A correção é uma regra que diz: se a requisição não corresponde a um arquivo real, sirva index.html com status 200 e deixe o roteador assumir. Como você adiciona isso depende da hospedagem (confira a documentação atual da sua, pois os detalhes mudam):

Hospedagem	Regra de fallback típica
Netlify	Um arquivo `_redirects` na pasta publicada com `/* /index.html 200`
Vercel	Um rewrite no `vercel.json` de todos os caminhos para `/index.html` (presets de frameworks costumam cuidar disso)
Cloudflare Pages	Serve fallback no estilo SPA por padrão quando não há um `404.html` na raiz
Nginx	`try_files $uri $uri/ /index.html;` no bloco `location /`
Apache	Uma regra de rewrite no `.htaccess` que envia requisições de não arquivos para `index.html`
GitHub Pages	Não tem rewrites no servidor; alternativas comuns são roteamento por hash ou um `404.html` que redireciona

Garanta que a regra não engula arquivos reais: requisições para /assets/app.js precisam continuar retornando o arquivo JavaScript. Se retornarem index.html, você verá uma página em branco com o erro “Failed to load module script”. Veja como corrigir uma tela branca.

Também dê ao roteador uma rota curinga para que URLs que não correspondam a nenhuma página mostrem uma mensagem amigável de “Página não encontrada”, em vez de nada.

Se você não puder alterar as configurações do servidor, o roteamento por hash (URLs como /#/dashboard) evita o problema, porque a parte depois do # nunca é enviada ao servidor. É um contorno, não a primeira escolha: as URLs são menos bonitas e menos amigáveis para mecanismos de busca.

Frameworks que renderizam páginas no servidor ou as geram no momento do build (Next.js, Astro e similares) normalmente têm arquivos reais ou rotas de servidor para cada página, então esse problema específico é menos comum neles. O equivalente lá é uma página que nunca foi gerada no build.

Passo 3: verifique o que foi publicado

Se tudo dá 404, o servidor provavelmente não está servindo o seu app compilado.

A pasta certa. A hospedagem deve publicar a saída do build (normalmente dist no Vite, build no Create React App, out para uma exportação estática do Next.js), e não a raiz do projeto.
O build rodou. Leia o log de publicação. Se o build falhou, a hospedagem pode não ter publicado nada, ou ter publicado uma versão antiga.
O index.html está no nível superior da pasta publicada, e não em uma subpasta.
O caminho base corresponde. Se o app é servido em exemplo.com/app/, ele precisa ser compilado com esse base (a opção base do Vite, o basename do React Router), senão todas as rotas e arquivos não serão encontrados.

Passo 4: corrija arquivos ausentes e caminhos errados

Quando as páginas carregam mas os recursos dão 404:

Diferenciação de maiúsculas e minúsculas. macOS e Windows normalmente tratam Logo.png e logo.png como o mesmo arquivo. A maioria dos servidores Linux não. Faça com que cada referência corresponda exatamente ao nome real do arquivo.
Arquivos fora do build. No Vite, os arquivos em public/ são copiados como estão e referenciados a partir da raiz (/logo.png). Arquivos importados no código são empacotados. Um arquivo em outro lugar do projeto pode nem ser publicado.
Caminhos relativos. images/foto.jpg é resolvido em relação à URL atual, então quebra em /blog/post-1. Use /images/foto.jpg.
Arquivos enviados salvos no disco local. Se os uploads dos usuários foram gravados na pasta do próprio servidor, eles desaparecem quando uma nova versão é publicada. Use um armazenamento de arquivos adequado.

Passo 5: trate as barras finais de forma consistente

/sobre e /sobre/ são URLs diferentes. As hospedagens diferem quanto a adicionar ou remover a barra final, e uma divergência com seus links ou com o roteador pode gerar 404s ou loops de redirecionamento. Escolha um estilo, faça seus links usarem esse estilo e configure a hospedagem para redirecionar a outra forma para ele. A consistência também ajuda os mecanismos de busca, que de outra forma podem enxergar duas cópias de cada página.

Passo 6: corrija rotas de API que dão 404

Se a página carrega, mas a aba Rede mostra requisições para /api/... retornando 404:

O backend não foi publicado. Uma hospedagem estática serve apenas arquivos; um backend precisa rodar em algum lugar.
O caminho é roteado de forma diferente em produção. Em desenvolvimento, um proxy pode ter encaminhado /api para um servidor separado. Em produção, a hospedagem precisa de um rewrite equivalente, ou o frontend precisa chamar o endereço real da API.
O fallback de SPA capturou a requisição. Uma requisição de API que retorna index.html com status 200 significa que a regra de fallback é ampla demais. Exclua /api/* dela.

As requisições do app publicado para /api/orders retornam 404, mas funcionam na prévia. Verifique como /api é roteado na prévia versus no app publicado, e faça o frontend publicado alcançar o backend do mesmo jeito.

Passo 7: redirecione URLs antigas

Se você migrou de outro site ou reestruturou o seu, URLs antigas que pessoas e mecanismos de busca ainda usam vão dar 404. Adicione um redirecionamento 301 (permanente) de cada URL antiga para o novo endereço. Mantenha uma lista e teste uma amostra depois do lançamento. Nosso guia sobre como migrar um site WordPress explica como montar essa lista.

Passo 8: verifique o domínio

Se o app funciona no endereço da hospedagem, mas dá 404 no seu domínio personalizado, o domínio pode estar apontando para o projeto errado, ou a hospedagem pode ainda não ter o domínio vinculado ao seu site. Verifique os registros de DNS e as configurações de domínio da hospedagem. Veja como conectar um domínio personalizado.

Deixe sua página 404 real útil

Alguns 404s são corretos: alguém digitou uma URL errada. Faça dessa página algo útil:

Uma mensagem curta e um link para a página inicial e as seções principais
Uma caixa de busca, se o site tiver busca
O mesmo cabeçalho e a mesma navegação do resto do site

Quando a sua configuração permitir, retorne um status 404 real para páginas que não existem. Uma mensagem de “não encontrado” retornada com status 200 é o que os mecanismos de busca chamam de soft 404, e isso pode desperdiçar tempo de rastreamento deles e confundir a indexação.

Erros comuns

Testar apenas clicando. Sempre teste colando URLs profundas em uma nova aba e atualizando.
Um fallback que captura tudo. Recursos e rotas de API retornam index.html, o que causa páginas em branco e erros de API confusos.
Capitalização incompatível que só quebra no servidor.
Publicar a pasta de código-fonte em vez da saída do build.
Reestruturar URLs sem redirecionamentos. Cada link antigo vira um 404.

404s na Mythex

Na Mythex você publica a partir do workspace, e frontends estáticos são publicados como sites estáticos. Se uma página publicada dá 404, informe ao agente a URL exata, se acontece ao atualizar ou ao clicar, e o que a aba Rede mostra, e peça para ele verificar o roteamento. Publique de novo depois da correção, pois o app no ar é um retrato até você publicar novamente. Se você mudou o projeto recentemente e o site no ar parece antigo, publique de novo e faça um atualização forçada. Use Corrigir com IA na janela de publicação se o build falhar. Veja Como publicar e Solução de problemas de publicação na documentação, e nosso guia sobre como depurar um app criado com IA.

Checklist para 404

Anotei exatamente quais URLs dão 404 e se acontece ao clicar, ao atualizar ou nos dois casos
O fallback de SPA serve index.html para as rotas do app, com status 200
O fallback exclui arquivos reais e /api/*
O roteador tem uma rota curinga de “não encontrado”
A pasta de saída do build é a que está publicada, e o build foi bem-sucedido
O caminho base corresponde ao local onde o app é servido
A capitalização dos nomes de arquivos corresponde a todas as referências
Os caminhos de recursos começam com /
O estilo da barra final é consistente
As rotas de API estão publicadas e roteadas em produção
Redirecionamentos 301 para URLs antigas
Links profundos testados colando-os em uma nova aba

Perguntas

Por que dou 404 quando atualizo uma página no meu app React?

Em um app de página única, rotas como /dashboard existem apenas no JavaScript. Clicar em um link funciona porque o roteador cuida disso no navegador, mas ao atualizar, o navegador pede ao servidor um arquivo /dashboard que não existe. A correção é uma regra de fallback que serve index.html para as rotas do app.

Como adiciono um fallback de SPA no Netlify, Vercel ou Nginx?

No Netlify, adicione um arquivo _redirects com /* /index.html 200. Na Vercel, adicione um rewrite no vercel.json que envia todos os caminhos para /index.html. No Nginx, use try_files $uri $uri/ /index.html; no bloco location. Confira a documentação da sua hospedagem, pois as regras mudam.

Por que minhas imagens ou arquivos dão 404 depois de publicar?

Geralmente o arquivo não está na saída do build, a capitalização do caminho não bate (servidores costumam diferenciar maiúsculas de minúsculas, o que o seu computador não faz), ou o caminho é relativo quando deveria começar com uma barra.

Uma página inexistente deve retornar um status 404 de verdade?

Sim. Mostre uma página de não encontrado útil, mas com status 404 quando a sua configuração permitir. Os mecanismos de busca tratam uma mensagem de “não encontrado” retornada com status 200 como um soft 404, o que desperdiça tempo de rastreamento e pode confundir a indexação.