logo hsb.horse
← Voltar para o índice do blog

Blog

Por que /blog retorna 404 no Astro + bun dev e como corrigir

Um fluxo prático de troubleshooting para 404 em /blog com Astro + bun dev, da verificação de links à inspeção de rotas e caminho de entrega. Inclui a correção de colisão de nome de diretório.

Publicado: Atualizado:

Ao executar bun dev, /blog/ retornava 404, mas /en/blog/ era renderizado corretamente.
A causa final não era a configuração de roteamento, e sim uma colisão de nome de diretório.

Sintomas

  • http://localhost:4321/blog/ retorna 404
  • http://localhost:4321/en/blog/ funciona
  • O build de produção (bun run build) ainda gera /blog/index.html

O que suspeitei primeiro

Primeiro suspeitei da geração de links e de paths por locale.

  • O href: "/blog" em HeaderNav estava quebrado?
  • getLocalePath() estava se comportando incorretamente apenas para japonês?
  • /blog estava sendo removido por prefixDefaultLocale: false?

Nenhum desses pontos era o problema.

Processo de verificação

Validei os fatos nesta ordem:

  1. Verificar saída estática
    • Os logs de bun run build incluem /blog/index.html
    • dist/blog/index.html realmente existe
  2. Verificar links renderizados
    • O link de navegação em dist/index.html é "/blog/"
    • O link em dist/en/index.html é "/en/blog/"
  3. Verificar comportamento de i18n
    • Com prefixDefaultLocale: false, japonês deveria ser /blog/
    • /ja/blog/ retornar 404 é esperado

Nesse ponto, a definição de rota e a geração de links já estavam corretas.

Causa raiz

Havia um diretório de nível superior blog/ usado para arquivos-fonte de artigos.
Ao mesmo tempo, o roteamento de páginas usava src/pages/blog/index.astro.

Assim, o diretório real blog/ entrou em conflito com o segmento de URL /blog.
No bun dev, essa colisão causou o 404.

Correção

  • Mover os arquivos-fonte de blog/ para content/blog/
  • Atualizar a base do loader em src/content.config.ts para ./content/blog

Depois disso, /blog/ passou a renderizar corretamente no bun dev.

Ordem de checagem reutilizável

Se o mesmo problema aparecer de novo:

  1. Confirmar que bun run build gera /blog/index.html
  2. Confirmar que o link em dist/index.html aponta para /blog/
  3. Confirmar o comportamento de prefixDefaultLocale e o /ja/blog/ esperado
  4. Verificar se existe diretório na raiz do projeto com o mesmo nome do segmento de URL

Principais aprendizados

  • Evite usar o mesmo nome para segmentos de URL do Astro e diretórios na raiz do projeto
  • Se build funciona e dev falha, compare primeiro o comportamento de entrega
  • Para depurar 404, separe a checagem em valores de link, geração de rota e arquivos reais