Next.js 배포 후 메타데이터 검증

Next.js 프로젝트를 배포했을 때, 로컬에서는 완벽했던 메타데이터가 운영 환경에서 제대로 렌더링되지 않을 때가 있다. 특히 동적 메타데이터를 사용할 때 문제가 두드러진다.

HTML Head 확인

배포 직후 가장 먼저 할 일은 실제 HTML을 확인하는 것이다:

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

이 명령어로 메타데이터가 실제로 렌더링되었는지 확인할 수 있다. 만약 <title> 태그가 없거나 generic한 값만 있다면 뭔가 잘못된 것이다.

메타데이터 정의 확인

Next.js 13+에서 메타데이터는 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: {
      title: post.title,
      description: post.excerpt,
      images: [post.image],
    },
  };
}

이 함수가 실제로 데이터베이스에서 정보를 가져오는지 확인해야 한다. 만약 데이터베이스 연결이 실패하면 메타데이터도 안 된다.

Canonical URL 설정

Canonical URL이 제대로 설정되지 않으면 검색 엔진이 같은 페이지를 중복으로 인식할 수 있다:

export async function generateMetadata(
  { params }
): Promise<Metadata> {
  const post = await getPost(params.id);
  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'https://example.com';
  return {
    title: post.title,
    alternates: {
      canonical: `${baseUrl}/blog/${post.slug}`,
    },
  };
}

특히 NEXT_PUBLIC_BASE_URL이 배포 환경에서 올바르게 설정되었는지 확인하자.

빌드 로그 분석

빌드 과정에서 메타데이터 생성에 문제가 있었는지 로그를 봐야 한다:

npm run build 2>&1 | tee build.log

ERROR나 WARN 메시지가 있는지 확인하자. 특히 generateMetadata를 호출하는 과정에서 네트워크 에러나 타임아웃이 발생했다면 메타데이터가 제대로 생성되지 않았을 것이다.

동적 메타데이터 문제

동적 메타데이터를 사용할 때는 다음을 확인해야 한다:

1. 데이터베이스가 빌드 타임에 접근 가능한가?
2. 네트워크 타임아웃 설정이 충분한가?
3. 외부 API 호출이 성공했는가?

만약 빌드 타임에 데이터를 가져올 수 없다면, 런타임에 가져오도록 변경해야 할 수도 있다.

Sitemap과 RSS 검증

Sitemap과 RSS도 메타데이터가 제대로 생성되었는지 보여주는 지표다:

curl -s https://example.com/sitemap.xml | head -20
curl -s https://example.com/feed.xml | head -20

이 파일들이 비어있거나 제너릭한 값만 있다면, Route Handler에서 데이터를 제대로 가져오지 못했다는 뜻이다.

실제 검증

1. 여러 페이지를 임의로 선택해서 확인한다.
2. 각 페이지의 title, description, og:image가 일치하는지 본다.
3. 구글 Search Console에서 크롤링 오류가 있는지 확인한다.
4. 소셜 미디어에서 공유했을 때 썸네일이 나오는지 테스트한다.

캐싱 설정

Next.js의 기본 캐싱 정책이 메타데이터를 제대로 반영하지 못할 수 있다:

export const revalidate = 3600; // 1시간마다 재검증

콘텐츠가 자주 변경된다면 적절한 revalidate 값을 설정해야 한다.

메타데이터는 사용자에게 직접 보이지 않지만, 검색 엔진과 소셜 미디어에는 큰 영향을 미친다. 배포 후 반드시 검증하는 습관을 들이자.