Publicação

Como corrigir erro 404 ao recarregar a página

Q: Por que o npm run preview não mostra o erro?

Porque o preview do Vite também tem a regra de página única ativada no modo padrão. Para reproduzir o problema, publique numa versão de teste da hospedagem e recarregue uma rota interna.

Q: Preciso mudar alguma coisa no código do React?

Na Netlify, Vercel, Cloudflare Pages, Apache e Nginx, não: a correção é só configuração da hospedagem. No GitHub Pages, você pode precisar ajustar o base do Vite e o basename do roteador.

Q: Esse erro atrapalha o SEO?

Sim. Se o Google recebe 404 nas rotas internas, elas não entram no índice. Mesmo corrigido, um site que monta tudo com JavaScript é lido com mais trabalho; para páginas que precisam ranquear, gerar o HTML no build ou no servidor ajuda.

Q: Sites feitos em Next.js ou Astro também têm esse problema?

Em geral não, porque eles geram um arquivo HTML para cada rota ou têm servidor próprio. O erro é típico de projetos React com Vite que usam só roteamento no navegador.

Q: Usei uma ferramenta de IA que publica sozinha. Onde coloco a regra?

Se a ferramenta publica na própria infraestrutura, a regra costuma vir pronta. Se você exportou o código para Netlify, Vercel ou outra hospedagem, siga o bloco correspondente a ela.

O erro 404 ao recarregar acontece em sites de página única (React, Vite, Vue) porque as rotas existem só no navegador: ao apertar F5 em /contato, a hospedagem procura um arquivo com esse nome e não encontra. A correção é configurar a hospedagem para devolver o index.html em qualquer rota que não seja um arquivo real. Na Netlify, a linha /* /index.html 200 no arquivo _redirects; na Vercel, um rewrite no vercel.json; no Apache, FallbackResource; no Nginx, try_files.

Atualizado em 10 de outubro de 2026 · Por Luis Henrique Cuba

Tirar minha dúvida com a LHCX

Por que funciona no npm run dev e quebra no ar

Num site de página única existe um só arquivo HTML, o index.html. Quando você clica num link interno, o roteador (React Router, por exemplo) troca a tela e muda a URL sem pedir nada ao servidor. Até aí tudo funciona.

O problema aparece quando alguém abre seudominio.com.br/contato direto, recarrega a página ou chega por um link compartilhado. Aí o navegador pede /contato à hospedagem, que procura um arquivo ou pasta com esse nome na pasta publicada (dist, no Vite). Não existe, e ela responde 404.

No computador isso não acontece porque o servidor de desenvolvimento do Vite, no modo padrão (appType: spa), já devolve o index.html para rotas desconhecidas. Em produção, essa regra precisa ser escrita na hospedagem.

Confirme que é esse o problema

A página inicial abre normalmente.
Navegar clicando nos links funciona.
Recarregar ou abrir uma rota interna direto mostra a página de erro da hospedagem, não a do seu site.
O projeto usa um roteador no navegador (React Router, Vue Router, TanStack Router ou similar).
Se em vez disso os arquivos .js e .css dão 404, o problema é o caminho base do build, não a rota. Veja o bloco do GitHub Pages.

A regra para cada hospedagem

01
Netlify
Crie o arquivo _redirects dentro da pasta public do projeto Vite, que é copiada para a raiz do dist no build. Se você já tem outras regras, essa costuma ser a última. A Netlify não sobrescreve arquivos que existem, então /assets/app.js continua sendo servido normalmente.
```
# public/_redirects
/*  /index.html  200

# ou, no netlify.toml
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
```
02
Vercel
Crie o vercel.json na raiz do projeto. A Vercel verifica primeiro se existe um arquivo com aquele caminho e só depois aplica o rewrite. Se o projeto usa cleanUrls: true, troque /index.html por /.
```
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}
```
03
Cloudflare Pages
Se o projeto publicado não tem um 404.html na raiz, o Cloudflare Pages já trata o site como página única e devolve o index.html. Se você criou um 404.html, esse comportamento deixa de valer.
04
Apache (hospedagem compartilhada, cPanel)
Crie um .htaccess na mesma pasta do index.html. A diretiva FallbackResource manda para o index.html só o que não é arquivo existente. Ela precisa de AllowOverride Indexes (ou All) liberado no servidor; se der erro 500, fale com a hospedagem.
```
# .htaccess
FallbackResource /index.html
```
05
Nginx (VPS)
Dentro do bloco server do site, o try_files tenta o arquivo, depois a pasta e, se nada existir, entrega o index.html. Depois de editar, teste a configuração com nginx -t e recarregue o Nginx.
```
location / {
    try_files $uri $uri/ /index.html;
}
```

GitHub Pages: o caso mais chato

O GitHub Pages não oferece um arquivo de reescrita como _redirects ou vercel.json. Ele aceita uma página 404.html personalizada, e é daí que vêm as soluções que circulam por aí.

Copiar o index.html para 404.html
Depois do build, duplique dist/index.html como dist/404.html. A rota passa a abrir o app, mas a resposta continua com código 404. Para o visitante funciona; para o Google, a página é um erro.
Usar rotas com #
No React Router, createHashRouter gera endereços como /#/contato. Tudo depois do # não vai ao servidor, então não há 404. O custo são URLs feias e ruins para SEO: o Google pede que apps de página única usem a History API, e não fragmentos, para separar o conteúdo.
Acertar o caminho base
Se o site fica em usuario.github.io/nome-do-repositorio/, a documentação do Vite pede base: "/nome-do-repositorio/" no vite.config. Sem isso, os arquivos .js e .css dão 404 e a tela fica branca. O roteador também precisa desse prefixo (basename no React Router).

Problemas que aparecem depois da correção

Tela branca e erro "Unexpected token <" no console
O navegador pediu um .js e recebeu o index.html. Em geral é o caminho base errado ou uma regra que força a reescrita mesmo de arquivos que existem (na Netlify, o 200! com exclamação faz isso).
Qualquer endereço inventado abre o site
É o efeito colateral da regra: /pagina-que-nao-existe também devolve 200. O Google pode marcar isso como soft 404. A orientação dele para apps de página única é mostrar uma tela de "não encontrada" com meta robots noindex, inserida por JavaScript, ou redirecionar para uma URL que responda 404 de verdade.
Regra criada no lugar errado
O _redirects precisa estar na pasta publicada. Se ele ficou na raiz do repositório e não em public, não vai para o dist e a Netlify não o encontra.
Rotas de API engolidas pela regra
Se o mesmo domínio tem funções em /api, coloque as regras delas antes da regra geral, para que não caiam no index.html.

Perguntas frequentes