Tutoriais de VPS
Erro 404 ao atualizar Vue ou React no Nginx: rotas e try_files
Se a página inicial funciona, mas uma rota profunda falha, separe páginas SPA, recursos e APIs. Configure o fallback e investigue JS que recebe HTML ou caminhos de subdiretório incorretos.

A página inicial do Vue ou React abre e navegar pelo menu até /dashboard funciona, mas atualizar essa URL retorna 404 do Nginx. Normalmente o navegador e o servidor estão tratando o caminho de formas diferentes. Outro erro comum é receber HTML com status 200 no lugar de JavaScript, deixando a página em branco.
Este guia se aplica a uma SPA estática já compilada e servida pelo Nginx. Confira requisições, arquivos e regras antes de adicionar fallback de página. Separe APIs e recursos estáticos. Uma aplicação Next.js ou Nuxt com renderização no servidor exige outra configuração.
Abra Network nas ferramentas do navegador, atualize a página e examine separadamente documento, JS/CSS e API. O texto do erro na tela não basta para decidir o que alterar.
| Resultado | Verifique primeiro | Tratamento correto |
|---|---|---|
Documento /dashboard retorna 404, mas navegação interna funciona | Fallback do modo History | Entregar o HTML de entrada para o frontend resolver a rota |
/assets/app-xxx.js retorna 404 | Build, caminho de recursos e cache antigo | Servir o arquivo real, nunca a página inicial como JS |
| JS retorna 200 com corpo HTML | Fallback capturando recursos | Retornar 404 real para arquivos ausentes |
/api/users retorna a página inicial | Regra de página capturando a API | Restaurar sua rota ou proxy separado |
A documentação do modo History do Vue Router explica a diferença: a navegação interna é tratada pelo navegador, enquanto o acesso direto a uma URL profunda precisa do documento de entrada. Entregar esse HTML não prova que a rota exista no frontend.
Para a saída padrão do Vite, execute o build existente do projeto e confirme o envio de dist/index.html e dos recursos referenciados. A documentação de implantação do Vite usa dist como diretório padrão e informa que vite preview é uma prévia local, não um servidor de produção.
Considere os arquivos em /srv/www/app/dist e o domínio app.example.com. Inspecione a configuração efetiva e os arquivos:
sudo nginx -T
ls -l /srv/www/app/dist/index.html
ls -l /srv/www/app/dist/assets/
Confira o server_name correspondente, o site HTTP/HTTPS e root. Um painel como Baota ou 1Panel pode gerar a configuração e sobrescrever alterações manuais. A saída de nginx -T pode conter endereços internos; remova-os antes de compartilhar.
Verifique maiúsculas e minúsculas: Logo.png funcionar localmente não significa que Linux o sirva como logo.png. Com Nginx em contêiner, confira os arquivos visíveis dentro dele; ter os arquivos no host não comprova o mount. Veja dados e mounts do Compose.
Este exemplo HTTP serve para domínio independente na raiz, sem API backend. Em HTTPS, incorpore as regras ao server existente e preserve os certificados. Se já existe API, mantenha suas regras reais; não as substitua pelo 404 de exemplo.
server {
listen 80;
server_name app.example.com;
root /srv/www/app/dist;
index index.html;
location = /index.html {
try_files $uri =404;
add_header Cache-Control "no-cache" always;
}
location ^~ /assets/ {
try_files $uri =404;
}
location ^~ /static/ {
try_files $uri =404;
}
location = /api {
return 404;
}
location ^~ /api/ {
return 404;
}
location / {
try_files $uri $uri/ /index.html;
}
}
Quando /dashboard não encontra um arquivo, faz um redirecionamento interno para /index.html. A regra separada do arquivo de entrada retorna 404 se ele também faltar, evitando redirecionamentos internos repetidos. no-cache permite armazenar em cache, mas exige revalidação antes do uso; não proíbe cache completamente.
/assets/ e /static/ são diretórios comuns de recursos. Crie regras próprias para outros diretórios do build, ou um JS ausente ainda pode cair no fallback. Um error_page 404 /index.html global pode esconder arquivos ausentes, APIs incorretas e erros reais de rota.
try_files verifica arquivos conforme o mapeamento; a URI final é o fallback. root acrescenta a URI ao diretório, conforme a referência do Nginx. Por exemplo, /assets/app.js sob root /srv/www/app/dist corresponde a /srv/www/app/dist/assets/app.js.
alias substitui o prefixo correspondente e usa outro cálculo de caminho. Não troque root e alias apenas para eliminar um 404. Veja no log qual arquivo o Nginx tentou abrir. Permission denied indica falta de permissão de leitura; outro fallback não resolve isso.
Para “Expected a JavaScript module … MIME type text/html” ou Unexpected token '<', abra Response na requisição que falhou. Se começa com <!doctype html>, normalmente é a página inicial ou um documento HTML de erro.
Depois de conferir caminho, arquivo e status, verifique se o contexto http carrega o mime.types adequado à instalação. Não force JavaScript como tipo padrão de todo o site: HTML, CSS e outros arquivos também ficariam incorretos.
Após publicar, um HTML antigo pode referenciar recursos com hash já removidos. Troque os arquivos como uma versão completa, preserve recursos antigos pelo tempo necessário e confira caches do navegador, Service Worker e CDN. Alterar cabeçalhos não recria um arquivo que falta.
Com CDN, compare primeiro status, Content-Type e corpo entre origem e borda. Limpe as URLs afetadas quando a origem estiver correta e a borda continuar desatualizada. Não atribua todo 404 ao CDN nem desative a verificação de certificados para esconder um problema HTTPS.
Se a URL real é https://example.com/app/, mudar a location para /app/ não basta. O base dos recursos do Vite, a base do roteador, a estrutura de diretórios e o fallback precisam corresponder ao prefixo.
Uma página em /app/ que solicita /assets/app.js pode fazer o servidor procurar na raiz do site principal. Configure as bases conforme o build e o roteador, recompile e examine URLs no HTML gerado. O exemplo de implantação na raiz não se aplica sem ajustes a um subdiretório.
Uma URL desconhecida da SPA ainda pode receber HTTP 200. O frontend deve exibir sua própria página não encontrada. Se você precisa de HTTP 404 correto para buscadores, use uma solução capaz de determinar rotas no servidor, em vez de tratar toda URL como válida.
Faça backup da configuração, valide a sintaxe e recarregue. Se a validação falhar, preserve a versão que está funcionando; veja falhas de configuração e reload do Nginx.
sudo nginx -t && sudo systemctl reload nginx
curl -i https://app.example.com/dashboard
curl -i https://app.example.com/assets/not-a-real-file.js
curl -i https://app.example.com/api/not-a-real-endpoint
Páginas profundas devem receber o HTML de entrada e JS ausente deve retornar 404. Uma API real deve responder JSON, erro de autenticação ou seu próprio 404, conforme o backend; nunca a página inicial. Atualize uma página profunda no navegador e confira execução dos scripts, login e carregamento de dados.
O artigo original registra 10 verificações isoladas com Nginx 1.19.6 em loopback: 200 em páginas profundas, tipos JS/CSS corretos, 404 para recursos ausentes e API de exemplo, e 404 sem loop quando o arquivo de entrada foi removido. Essa versão local não é uma recomendação para produção. Os testes não cobrem execução real do frontend, TLS, CDN, Service Worker ou login da aplicação.