Next.js 배포 후 메타데이터가 없을 때

링크를 공유했는데 썸네일이나 설명이 나오지 않는다. 크롤러가 메타데이터를 읽지 못한다는 뜻이다. 로컬에서는 보이는데 배포 후에 안 보이는 경우가 대부분이다.

서버 응답 직접 확인

SNS나 검색 엔진은 JavaScript를 실행하지 않는다. HTML에 직접 적혀 있는 메타데이터만 본다:

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

og:title, og:description, og:image 태그가 HTML 헤더에 있는지 확인하자. 없으면 메타데이터가 제대로 생성되지 않은 것이다.

Next.js metadata 설정

App Router를 쓴다면 각 페이지의 layout.ts 또는 page.ts에서 metadata를 export해야 한다:

export const metadata: Metadata = {
  title: 'Article Title',
  description: 'Article description',
  openGraph: {
    title: 'Article Title',
    description: 'Article description',
    url: 'https://example.com/article/123',
    image: 'https://example.com/image.jpg'
  }
};

이 설정은 서버에서 렌더링될 때 HTML 헤더에 자동으로 추가된다.

빌드 후 확인

npm run build

빌드 로그에서 경고가 있는지 확인하자. 예를 들어 "Invalid metadata" 같은 메시지가 있으면 설정이 틀렸다는 뜻이다.

동적 메타데이터

페이지마다 다른 메타데이터를 보여줄 때 generateMetadata 함수를 사용한다:

export async function generateMetadata(
  { params }: { params: { id: string } }
): Promise<Metadata> {
  const post = await getPost(params.id);

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      image: post.imageUrl
    }
  };
}

이 함수는 각 페이지를 빌드할 때 호출되어 정확한 메타데이터를 생성한다.

캐시와 CDN

배포 후에도 메타데이터가 안 보인다면 캐시 때문일 수 있다. 특히 CDN이나 브라우저 캐시:

1. 브라우저 캐시 비우기
2. 페이지 캐시 비우기 (Vercel 대시보드에서 가능)
3. 필요하면 CDN 캐시도 무효화

크롤러 테스트

실제로 SNS나 검색 엔진이 어떻게 봤는지 테스트해보자:

• Twitter Card Validator: https://cards-dev.twitter.com/validator
• Facebook Sharing Debugger: https://developers.facebook.com/tools/debug/
• Google Rich Results Test: https://search.google.com/test/rich-results

이 도구들은 실제 크롤링 방식을 시뮬레이션한다.

배운 점

메타데이터는 크롤러가 JavaScript 실행 없이 HTML 소스에서 직접 읽는다. 브라우저에서 보이는 것과 크롤러가 보는 것은 다를 수 있다.

curl로 직접 응답을 확인하는 습관이 메타데이터 문제를 빠르게 찾아준다.