Roteamento baseado em hash versus baseado em caminho

As SPAs precisam de endereços que o navegador não busque. Há duas abordagens: a baseada em fragmentos usa o fragmento (tudo depois de #), que o navegador nunca envia ao servidor, e a baseada em caminhos usa o caminho junto com recursos da API de histórico.

Os endereços têm a aparência https://example.com/#/about. O servidor vê apenas / e fornece o mesmo HTML para todos os endereços. O JS do cliente lê location.hash para decidir qual visualização renderizar. É simples e não exige configuração do servidor.

Os roteadores baseados em fragmentos escutam o evento hashchange, que é disparado sempre que location.hash muda. Combinado com a leitura do fragmento na localização da janela, isso é toda a API necessária para o roteamento no cliente — sem envolver a API de histórico.

Os endereços têm a aparência https://example.com/about — indistinguível dos endereços renderizados pelo servidor. pushState, da API de histórico, altera o caminho sem recarregar a página; o evento de navegação no histórico é disparado ao voltar ou avançar; a interceptação de cliques transforma <a> em navegação de SPA.

No roteamento baseado em caminhos, o servidor deve retornar o index.html da SPA para qualquer caminho que o usuário possa inserir diretamente (ou atualizar). Caso contrário, atualizar /about resulta em um erro 404. Configure assim: tente o arquivo e, como alternativa, use index.html (fallback de histórico no Nginx, vite-plugin-history-api no Vite de desenvolvimento).

Os mecanismos de busca e muitas ferramentas não conseguem rastrear fragmentos de hash — o conteúdo em /#/about fica invisível para rastreadores antigos (o Google lida com isso por meio de renderização sem interface, mas outros talvez não). Os endereços baseados em caminhos são rastreados normalmente, o que os torna muito melhores para SEO.

Os endereços com fragmentos parecem visivelmente "estranhos" — os usuários percebem o # e talvez não confiem no link nem se lembrem de copiar o endereço completo. Os endereços baseados em caminhos têm a aparência de qualquer outro endereço da Web, que é o que os usuários esperam. Só por esse motivo, as SPAs modernas quase sempre escolhem o roteamento baseado em caminhos.

Baseado em fragmentos: cerca de 10 linhas de JS (ouvinte de alterações do fragmento e renderização). Baseado em caminhos: chamadas a pushState, ouvinte de navegação no histórico, interceptação de cliques em links e fallback no servidor. Fragmentos são a opção mais simples possível; caminhos exigem mais infraestrutura para proporcionar uma experiência melhor ao usuário.

Hospedagens totalmente estáticas (a configuração padrão do GitHub Pages) não conseguem fazer fallback no servidor, então o roteamento baseado em caminhos deixa de funcionar ao atualizar a página. Alternativas: truques de redirecionamento em 404.html, hospedar no Netlify/Vercel (que entendem o fallback de SPA) ou aceitar o roteamento baseado em fragmentos em projetos que usam apenas hospedagem estática.

Alguns aplicativos combinam as duas abordagens: caminhos para a rota principal e fragmentos para seções dentro da página (janelas modais, âncoras de abas). O evento de alteração do fragmento ainda é disparado nesses casos, complementando o roteador baseado no histórico para o estado de subpáginas sem poluir o endereço principal.

Para migrar de fragmentos para caminhos: reescreva todos os links internos, adicione o fallback do servidor, substitua a lógica de alteração do fragmento pela navegação no histórico e redirecione os endereços antigos com fragmentos para os equivalentes baseados em caminhos usando um pequeno script de inicialização que seja executado uma vez e chame history.replaceState.

Escolha o roteamento baseado em fragmentos para: hospedagens estáticas sem reescritas, ferramentas administrativas internas nas quais SEO não importa e componentes incorporados. Escolha o roteamento baseado em caminhos para: qualquer aplicação voltada aos usuários, qualquer aplicação que deva ser indexada por SEO e qualquer aplicação compartilhada nas redes sociais — ou seja, a maioria dos aplicativos.

Por que o roteamento de SPA baseado em caminhos exige uma configuração do servidor que o roteamento baseado em fragmentos não exige?

O roteamento baseado em fragmentos (endereços como /#/about) não precisa de configuração do servidor, mas tem SEO fraco e usa endereços pouco atraentes. O roteamento baseado em caminhos (endereços como /about) precisa de um fallback do servidor para index.html, mas produz endereços limpos, favoráveis ao SEO e fáceis de compartilhar. As SPAs modernas voltadas ao público usam caminhos; projetos internos ou hospedados estaticamente ainda podem escolher fragmentos pela simplicidade.