Next.js 메타데이터 문제: 모바일에서 공유 이미지가 안 보일 때

모바일에서 링크를 공유했는데 미리보기가 제대로 표시되지 않는 경우가 생긴다. 원인을 찾으려면 화면만 봐서는 안 되고, 실제 HTML head에 뭐가 들어갔는지 확인해야 한다.

문제 상황 파악

처음부터 광범위하게 의심하면 손댈 부분이 너무 많아진다. 먼저 실제 페이지의 HTML을 직접 확인하는 게 빠르다. 재현 조건도 중요한데, 로컬에서는 괜찮은데 배포된 서버에서 문제가 나는 경우도 흔하다.

HTML head 확인하기

가장 먼저 할 일은 배포된 URL에서 실제 렌더링된 HTML을 보는 것이다:

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

이 명령어로 head 섹션의 주요 태그들을 한눈에 볼 수 있다. og:image가 제대로 들어갔는지, canonical은 올바른지 확인한다.

Next.js 빌드 상태 확인

local 환경에서 잘 보인다고 해서 production에서도 같다고 보면 안 된다. 빌드 과정에서 환경변수나 설정이 다르게 적용될 수 있다:

npm run build

빌드 로그를 확인해서 경고나 에러가 없는지 보자. 빌드는 성공했지만 메타데이터가 누락되는 경우도 있다.

메타데이터 설정 검토

Next.js 13.2 이후라면 metadata 객체를 사용하고, 그 전이면 next/head를 쓴다. 각 페이지가 metadata를 올바르게 export하고 있는지 확인한다. 만약 동적 경로라면 generateMetadata 함수가 제대로 실행되는지도 봐야 한다.

공개 URL에서 최종 확인

수정한 후에는 실제 공개된 페이지에서 다시 확인한다. 캐시 때문에 바로 반영 안 될 수도 있으니 시간을 두고 보는 것도 방법이다. 소셜 미디어의 URL 디버거(예: Facebook 공유 디버거, Twitter Card validator)를 써서 검증하는 게 확실하다.

마지막으로, 비슷한 문제가 나중에 다시 생기면 빌드 로그, 실제 HTML 출력, 메타데이터 설정 세 가지를 함께 기록해두면 다음에 훨씬 빠르게 원인을 찾을 수 있다.