Astro 하이브리드 모드에서 동적 라우트 정적 빌드 누락 수정

Astro 기반 정적 사이트에서 동적 라우트 두 개가 빌드 시 페이지를 생성하지 못하고 있던 걸 발견해서 수정했다.

왜 이게 빠져 있었나

[...slug].astro와 c/[category].astro, 두 파일 모두 동적 라우트다. Astro의 기본 동작은 output: 'static' 모드일 때 getStaticPaths()를 통해 경로를 미리 수집하고 빌드 타임에 HTML을 생성한다. 그런데 이 두 파일에 prerender = true 설정이 빠져 있었다.

이게 문제가 되는 건 Astro 프로젝트가 output: 'hybrid' 또는 output: 'server' 모드로 구성되어 있을 때다. 이 모드들은 기본값이 SSR이기 때문에, 페이지마다 명시적으로 prerender = true를 선언하지 않으면 빌드 시 정적 HTML로 뽑히지 않고 런타임에 서버 렌더링 경로로 취급된다. 결과적으로 CDN 캐싱도 안 되고, 정적 호스팅 환경이라면 해당 경로가 아예 404로 떨어지는 상황이 벌어진다.

---
// 수정 전 — prerender 선언 없음
// hybrid 모드에서는 SSR로 fallback됨
export async function getStaticPaths() {
  // ...
}
---

---
// 수정 후
export const prerender = true;

export async function getStaticPaths() {
  // ...
}
---

한 줄 추가지만 이 한 줄이 빌드 결과물에서 해당 라우트의 존재 여부를 결정한다.

두 라우트의 역할과 영향

[...slug]는 rest parameter 방식이라 depth가 몇이든 받아낼 수 있는 범용 라우트고, c/[category]는 단일 세그먼트를 받는 카테고리 인덱스 라우트다. 두 라우트 모두 콘텐츠 탐색의 핵심 경로인데, 여기서 prerender가 빠지면 사이트 구조 자체가 흔들린다.

팀 입장에서 이런 실수가 발생하는 패턴을 짚어보면, 보통 다음 중 하나다.

• 새 페이지 파일을 기존 static 전용 프로젝트에서 복사해 왔는데, 그 사이에 프로젝트 설정이 hybrid로 바뀐 경우
• output 모드 변경 작업을 하면서 기존 동적 라우트 파일들을 일괄 점검하지 않은 경우
• 개발 서버(astro dev)에서는 문제없이 동작하다 보니 빌드 테스트를 늦게 돌린 경우

세 번째가 제일 위험하다. astro dev는 요청 시마다 렌더링하기 때문에 prerender 여부와 무관하게 페이지가 잘 뜬다. 로컬에서 다 된다고 확인하고 PR 올렸는데 빌드 산출물에서 해당 경로가 없는 걸 배포 후에야 발견하면 그게 제일 아프다.

회고

이런 종류의 fix는 코드 자체는 단순하지만, 발견 시점이 늦어질수록 파장이 커진다. prerender 누락은 빌드 로그에서 에러를 내지 않는다. 그냥 조용히 그 경로가 정적 빌드 산출물에서 사라질 뿐이다.

코드리뷰 때도 이 부분을 체크리스트에 넣어두는 게 좋다. hybrid/server 모드 프로젝트에서 새로운 동적 라우트 파일이 PR에 들어온다면, prerender 선언 여부를 리뷰어가 확인하는 게 기본이어야 한다. 안 그러면 이번처럼 빌드 후에 발견하거나, 운이 나쁘면 배포 후 트래픽 타면서 발견한다.

멘토링할 때도 자주 하는 말이지만, Astro처럼 모드별로 렌더링 전략이 달라지는 프레임워크는 dev와 build 결과가 다르게 동작할 수 있는 케이스를 팀 전체가 인지하고 있어야 한다. "로컬에서 됐는데요"가 통하지 않는 유형의 버그가 여기서 나온다.

끝.

🛒 이 글과 어울리는 추천 상품

• 노트북 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.