Next.js metadata가 예상과 다를 때 확인할 것

Next.js metadata를 다룰 때 놓치기 쉬운 부분이 있다. 로컬에서는 잘 보이는데 배포하면 canonical이 없어진다거나, og:image가 404가 된다거나.

먼저 HTML head 확인하기

# 배포된 페이지의 실제 HTML 확인
curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'

이 명령어로 보이는 게 실제 상태다. 개발자 도구는 클라이언트 렌더링 후의 상태만 보여주므로 참고만 하자.

Canonical 문제가 가장 흔함

Canonical이 상대 경로로 나가는 경우가 대부분이다. 예를 들어:

// 잘못된 예
canonical: '/posts/my-article' // 도메인이 없음

// 올바른 예
canonical: `${process.env.NEXT_PUBLIC_SITE_URL}/posts/my-article`

process.env.NEXT_PUBLIC_이 붙어야 빌드 타임에 치환된다. 그리고 배포 환경의 .env.production에 반드시 정의돼 있어야 한다.

빌드 로그 읽기

npm run build

Build 마지막 부분에 "Generating static pages..." 같은 메시지가 있다. 여기서 metadata 최종 값들이 나간다. 콘솔에 실제 URL이 보이는지 확인하자.

공개 URL로 최종 확인

1. 로컬에서 metadata가 생성되는 방식 이해 (빌드 타임 vs 런타임)
2. HTML head의 실제 결과물 확인
3. 각 환경별로 배포 후 재검증

이 세 단계를 거치면 대부분의 문제가 해결된다.