Astro + bun dev 환경에서 /blog 404의 원인과 해결 절차

bun dev 실행 중 /blog/는 404인데 /en/blog/는 정상 표시되는 현상을 만났다.
결론적으로 원인은 라우팅 설정이 아니라 디렉터리 충돌이었다.

증상

• http://localhost:4321/blog/ 는 404
• http://localhost:4321/en/blog/ 는 정상 표시
• 프로덕션 빌드(bun run build)에서는 /blog/index.html이 생성됨

처음 의심한 부분

처음에는 링크 생성 문제를 의심했다.

• HeaderNav의 href: "/blog"가 깨졌는가
• getLocalePath()가 일본어에서만 잘못 동작하는가
• prefixDefaultLocale: false 때문에 /blog가 사라지는가

결론: 모두 문제가 아니었다.

검증 프로세스

아래 순서로 사실을 쌓아 갔다.

1. 정적 출력 확인
   • bun run build 로그에 /blog/index.html이 표시됨
   • dist/blog/index.html이 실제로 존재함
2. 실제 렌더 결과 링크 확인
   • dist/index.html의 내비 링크가 "/blog/"임
   • dist/en/index.html은 "/en/blog/"임
3. i18n 규칙 확인
   • prefixDefaultLocale: false에서 일본어의 올바른 URL은 /blog/
   • /ja/blog/가 404인 것은 규칙상 정상

여기까지 확인하면 라우트 정의와 링크는 정상이라고 확정할 수 있다.

근본 원인

프로젝트 루트에 콘텐츠용 디렉터리 blog/가 있었다.
동시에 페이지 라우트로 src/pages/blog/index.astro를 사용하고 있었다.

즉, 실디렉터리 blog/와 URL 세그먼트 /blog가 같은 이름으로 충돌했다.
bun dev에서는 이 충돌이 404로 나타났다.

수정

• 콘텐츠 위치를 blog/에서 content/blog/로 이동
• src/content.config.ts의 loader base를 ./content/blog로 변경

이후 bun dev에서도 /blog/가 정상 표시되었다.

재발 시 확인 순서

같은 증상이 나오면 아래 순서가 빠르다.

1. bun run build에서 /blog/index.html 생성 여부 확인
2. dist/index.html의 내비 링크가 /blog/인지 확인
3. prefixDefaultLocale 설정을 확인하고 /ja/blog/ 기대값 정리
4. URL 세그먼트와 같은 이름의 루트 디렉터리가 있는지 확인

배운 점

• Astro의 URL 세그먼트와 프로젝트 루트 디렉터리 이름은 겹치지 않게 관리한다
• 빌드는 통과하지만 dev만 실패하면 전달 경로 우선순위 차이를 먼저 의심한다
• 404 분석은 링크 값, 라우트 생성, 실파일을 분리해 확인하면 빠르다

관련 링크

• Blog content collection design
• i18n URL strategy for an Astro site
• Astro: Routing
• Astro: Internationalization (i18n)