Next.js 동적 렌더링이 제대로 작동하지 않을 때

Next.js에서 동적 페이지의 메타데이터가 제대로 나타나지 않으면 혼란스럽다. 화면에만 집중하면 모든 파일이 의심스러워진다. 핵심은 좁은 범위에서부터 시작해서 점점 확대하는 것이다.

먼저 해당 페이지가 정말 동적 렌더링(Dynamic Rendering) 모드인지, 아니면 정적 생성(Static Generation)인지 확인한다. 렌더링 방식에 따라 메타데이터가 정해지는 시점이 다르기 때문이다.

페이지 소스에서 메타데이터 확인

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
npm run build

HTML head에 있는 실제 메타데이터를 본다. 브라우저 화면에서 보이는 것과 페이지 소스가 다를 수 있다. 소셜 미디어나 검색 엔진은 페이지 소스를 보기 때문에, 소스에 있는 메타데이터가 맞는지 확인하는 게 중요하다.

canonical과 og:url 확인

canonical 태그와 Open Graph URL이 정확한지 본다. 현재 페이지 경로와 메타데이터의 URL이 일치하지 않으면 검색 엔진에서 혼란스러워한다. 동적 페이지라면 각 페이지 ID나 slug가 제대로 URL에 반영되는지 확인한다.

빌드 단계의 로그

빌드 로그에서 "ISR(Incremental Static Regeneration)" 또는 "dynamic route" 관련 메시지를 찾는다. 빌드가 경고나 에러를 내보낸다면 그게 메타데이터 생성 실패의 원인일 가능성이 크다.

한 페이지씩 테스트

여러 동적 페이지가 있다면 하나씩 테스트한다. A 페이지는 메타데이터가 맞는데 B 페이지는 틀렸다면, 두 페이지의 메타데이터 생성 방식이 뭐가 다른지 비교한다. 이렇게 하면 문제가 특정 페이지에만 있는지, 아니면 전역 설정의 문제인지 구분할 수 있다.