Next.js의 메타 데이터 설정 문제 디버깅

Next.js에서 메타데이터를 설정하는 방법이 여러 개다. 헤드 태그에 직접 작성, metadata 객체, generateMetadata 함수. 각각이 다르게 작동할 수 있고, 로컬과 운영 환경에서 다른 결과가 나올 수 있다.

메타데이터가 필요한 이유

SEO, 소셜 미디어 공유, 브라우저 탭 제목 등 메타데이터가 사용되는 곳은 많다. 각각의 용도를 명확히 하면 어느 부분이 잘못됐는지 빨리 찾을 수 있다.

현재 상태 확인

canonical 링크, Open Graph 태그, Twitter 카드, viewport 설정 등이 HTML의 head에 제대로 들어가 있는지 확인한다.

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

로컬과 운영 비교

로컬 개발 환경에서는 동적 메타데이터가 제대로 생성되지 않을 수 있다. 환경 변수, 배포 URL, 동적 라우팅이 다르기 때문이다.

• 확인할 것: canonical 링크, og:image, og:url
• 비교 기준: 정상일 때의 HTML head
• 기록할 것: 현재 값, 기대하는 값, 환경 설정

빌드 로그 확인

빌드 시 경고가 있는지, 메타데이터 생성이 제대로 이루어졌는지 로그에서 확인한다.

수정 순서

metadata 설정을 변경할 때는 한 가지씩만 수정하고, 각 단계마다 결과를 확인한다. title 수정? og:image 수정? 각각을 별도로 진행한다.

HTML 검증

canonical 링크, og:url 등이 현재 페이지를 올바르게 가리키는지 확인한다. 특히 다중 언어나 동적 라우팅을 사용한다면 더 주의해야 한다.

# 배포 후 실제 페이지 확인
curl -s https://example.com/page | head -20

다음 액션

HTML head의 값이 달라졌다면, 왜 그렇게 변했는지 설명할 수 있어야 한다. 환경 변수 때문? 동적 생성 로직 때문? 빌드 설정 때문?

완료 기준

1. 메타데이터가 실제 HTML에 들어가 있는가
2. 로컬과 운영의 메타데이터가 일치하는가
3. SEO 검사 도구(Lighthouse, SEO 확장 프로그램)에서 경고가 없는가

메타데이터는 사용자에게는 보이지 않지만, 검색 엔진과 소셜 미디어 플랫폼에는 매우 중요하다. 정확히 설정하는 것이 사이트의 가시성을 크게 높인다.