Next.js 배포 후 메타데이터가 안 적용될 때

Next.js로 만든 블로그나 웹사이트를 배포했는데, 소셜 미디어에 공유할 때 제목과 설명이 제대로 안 뜨는 경우가 있다. 로컬에서는 잘 보이는데, 배포 환경에서만 문제가 생기는 게 대부분이다.

핵심은 메타데이터 문제를 '콘텐츠 데이터'의 문제로만 보지 말고, build 설정과 배포 환경의 차이를 함께 봐야 한다는 것이다.

배포된 페이지에서 HTML 직접 확인

먼저 브라우저에서 실제 배포 페이지의 HTML을 본다.

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

개발자 도구에서는 클라이언트 사이드 렌더링된 상태를 보지만, 소셜 미디어 크롤러는 초기 HTML만 본다.

Next.js build 결과 확인

Production build 후 .next 디렉토리의 정적 파일들을 직접 본다. 메타데이터가 build 시점에 정적으로 삽입되는지, 아니면 런타임에 동적으로 주입되는지 확인한다.

npm run build
# .next/server/pages나 .next/static 디렉토리의 HTML 파일들을 확인

환경변수 확인

메타데이터에 사이트 도메인이나 다른 환경변수가 포함되어 있다면, 배포 환경의 환경변수가 제대로 설정되었는지 확인한다. NEXT_PUBLIC_으로 시작하는 변수들은 build 시점에 static하게 삽입된다.

# 배포 환경의 환경변수 확인
echo $NEXT_PUBLIC_BASE_URL

동적 라우팅과 메타데이터

동적 라우트(예: /posts/[id])를 사용하면, 각 페이지의 메타데이터가 다르게 적용되어야 한다. 데이터베이스에서 잘못된 데이터를 가져오거나, 데이터 없이 빌드되었을 수도 있다.

# 특정 페이지의 메타데이터 확인
curl -s https://example.com/posts/some-id | grep 'og:title'

배포 후 캐시 문제

CDN이나 브라우저 캐시 때문에 오래된 HTML이 계속 제공될 수도 있다. 캐시를 무시하고 실제 콘텐츠를 요청해본다.

curl -s -H "Cache-Control: no-cache" https://example.com/post/my-post

소셜 미디어 크롤러로 테스트

Facebook 셰어 디버거나 Twitter 카드 validator로 실제 크롤러가 뭘 보는지 확인한다. 이들은 초기 HTML만 파싱하므로, JavaScript로 주입되는 메타데이터는 보지 못한다.

1. 배포 환경의 실제 HTML을 curl로 본다.
2. Open Graph와 Twitter Card 메타데이터가 있는지 확인한다.
3. 메타데이터의 도메인이 배포 환경과 일치하는지 본다.

마지막 확인

메타데이터를 수정한 후에는 배포를 다시 하고, 충분한 시간을 둔 후에 소셜 미디어에 다시 공유해본다. 캐시 때문에 즉시 반영되지 않을 수 있다.