Next.js에서 상태 초기화 후 메타데이터가 안 나올 때

Next.js 앱에서 상태 관리를 리팩터링하거나 Redux, Zustand 같은 라이브러리를 초기화하면, 로컬에서는 잘 작동하지만 배포 후 메타데이터(Open Graph, canonical 등)가 없어지는 문제가 생길 수 있다. 이는 보통 서버 렌더링 시점과 클라이언트 하이드레이션 시점의 상태가 달라서 발생한다.

공개 URL의 실제 HTML 확인

먼저 배포된 서버에서 실제로 뭘 전송하는지 확인해야 한다. 메타데이터가 빠졌다면 서버 렌더링 시점에 문제가 있다는 뜻이다.

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

이 명령어로 보이지 않는 태그가 있다면, 서버 렌더링 단계에서 메타데이터 함수가 제대로 실행되지 않은 것이다.

sitemap과 RSS 피드 확인

Next.js 앱에서 sitemap.ts, robots.ts, feed.xml 같은 정적 파일들도 메타데이터 함수에 의존할 수 있다. 이들이 제대로 생성되었는지 확인해보자.

URL들이 sitemap에 나타나는가? RSS 피드의 각 항목에 제목과 설명이 있는가? 이들이 빠졌다면, 메타데이터 함수 자체가 실행되지 않았거나 에러를 던진 것이다.

빌드 로그와 상태 초기화 순서

상태 관리를 바꿀 때 초기화 순서가 중요하다. 메타데이터를 생성하기 위해 필요한 데이터가 준비되기 전에 렌더링이 시작되면 메타데이터가 없게 된다.

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

local에서 빌드할 때 로그를 보면:

• 어떤 페이지들이 정적으로 생성되었는지 (prerendered)
• 어떤 페이지들이 동적으로 생성되도록 설정되었는지 (on-demand ISR)

이 정보들을 배포 후 결과와 비교해서, 빌드 시점의 설정과 런타임 설정이 일치하는지 확인하자.

메타데이터 함수 내 상태 의존성 확인

메타데이터를 생성하는 함수 내에서 상태 관리 라이브러리를 사용하고 있다면, 그 라이브러리의 초기화가 제대로 이루어져야 한다.

예를 들어 Zustand를 쓴다면, 메타데이터 함수가 실행되는 서버 사이드 환경에서 스토어가 제대로 초기화되어 있는가?

Redux라면, 서버 사이드 렌더링을 위한 스토어 생성 로직이 메타데이터 함수 실행 전에 완료되어야 한다.

검증: 단계별 확인

1. npm run build로 로컬 빌드하고, 빌드 로그에서 메타데이터가 생성되는 페이지들이 있는지 확인
2. npm run start로 로컬 운영 서버를 실행하고, curl로 메타데이터가 나오는지 확인
3. 배포 후 같은 방식으로 curl을 실행해서 결과 비교

세 단계 모두에서 메타데이터가 있어야 제대로 작동하는 것이다.