Next.js metadata가 적용되지 않을 때 확인할 7가지

이 글의 검색 의도: Next.js App Router에서 metadata를 작성했는데 title, description, OG 이미지가 적용되지 않을 때 확인하는 오류 해결 체크리스트입니다. Metadata API의 전체 개념은 Next.js App Router metadata 가이드와 Next.js Metadata API 정리에서 더 자세히 볼 수 있습니다.

Next.js metadata가 적용되지 않을 때 확인할 7가지

metadata 또는 generateMetadata를 app/layout.tsx나 app/page.tsx 같은 Server Component 파일에서 export했는지 확인합니다.
같은 route segment에서 metadata 객체와 generateMetadata 함수를 동시에 export하지 않았는지 확인합니다.
동적 페이지라면 generateMetadata가 params, searchParams, 상위 metadata를 올바르게 읽고 있는지 확인합니다.
metadataBase가 없어 상대 OG URL이나 canonical URL이 기대와 다르게 생성되지 않았는지 확인합니다.
opengraph-image, twitter-image, favicon 같은 file-based metadata가 코드 metadata보다 우선하는지 확인합니다.
title.template과 title.default를 layout에 두고, 개별 page title이 기대대로 조합되는지 확인합니다.
소셜 미리보기는 각 플랫폼 캐시가 남을 수 있으므로 공개 HTML head 확인 후 디버거에서 다시 스크랩합니다.

실제 증상 예시

metadata title이 브라우저 탭에 반영되지 않음
Open Graph 이미지가 카카오톡/Discord 미리보기에서 이전 이미지로 보임
동적 상세 페이지마다 같은 title이 노출됨

잘못된 코드와 수정 코드

잘못된 예: Client Component에서 metadata export

'use client';

export const metadata = {
  title: '게시글 상세',
};

좋은 예: 서버 컴포넌트 page/layout에서 export

export const metadata = {
  title: '게시글 상세',
  description: '게시글 상세 페이지입니다.',
};

export default function PostPage() {
  return <main>본문</main>;
}

같이 보면 좋은 글

Next.js metadata FAQ

metadata는 모든 페이지에서 자동으로 합쳐지나요?

상위 layout의 metadata와 하위 page metadata가 병합되지만 필드별로 덮어쓰기 규칙이 다릅니다. 중요한 페이지는 실제 HTML head 출력으로 확인하는 것이 안전합니다.

동적 페이지 title은 어디서 만들어야 하나요?

상품 상세나 게시글 상세처럼 데이터에 따라 title이 바뀌면 generateMetadata를 사용합니다. 이 함수는 서버에서 실행되므로 필요한 데이터를 가져와 title과 description을 만들 수 있습니다.

수정했는데 검색 결과 title이 바로 안 바뀝니다. 정상인가요?

정상일 수 있습니다. 사이트 HTML에는 반영되어도 Google 검색 결과는 재크롤링과 재처리 시간이 필요합니다. 먼저 공개 HTML의 title이 바뀌었는지 확인하세요.

Next.js metadata가 적용되지 않을 때 확인할 것에서 먼저 확인할 것

Next.js metadata가 적용되지 않을 때는 먼저 App Router의 Metadata API가 읽히는 위치를 확인합니다. metadata와 generateMetadata는 Server Component route segment에서만 지원되며, 파일 기반 metadata, title template, 배포/소셜 캐시까지 함께 확인해야 합니다.

Next.js metadata가 적용되지 않을 때 확인할 7가지
실제 증상 예시
잘못된 코드와 수정 코드
같이 보면 좋은 글
Next.js metadata FAQ
Next.js metadata가 적용되지 않을 때 확인할 것에서 먼저 확인할 것
증상부터 정확히 보기
왜 이런 문제가 생기는지
실제 코드에서 고치는 방법
수정 후 확인할 체크리스트
정리

증상부터 정확히 보기

Next.js metadata 적용 오류 진단: layout page metadata API와 head 출력 확인 흐름

Next.js metadata가 적용되지 않을 때 먼저 볼 것은 수정한 파일이 실제 route segment의 layout.tsx 또는 page.tsx인지입니다. use client가 있는 파일에서는 metadata와 generateMetadata export가 지원되지 않으므로, 클라이언트 UI가 필요하면 metadata는 부모 Server Component에 두고 화면만 Client Component로 분리합니다.

입문 단계에서는 문제를 빨리 없애려고 가장 강한 해결책부터 붙이기 쉽습니다. 하지만 그렇게 처리하면 다음 화면에서 비슷한 문제가 반복됩니다. 작은 재현 코드로 줄이고, 어떤 값이 어느 시점에 바뀌는지 확인하는 편이 더 안전합니다.

왜 이런 문제가 생기는지

이 문제의 중심에는 Next.js가 route segment별 metadata를 해석하고 병합하는 방식이 있습니다. 정적 값은 metadata 객체로 충분하고, params나 외부 데이터에 따라 title과 description이 달라져야 하면 generateMetadata를 사용합니다. 같은 segment에서 두 방식을 동시에 export하면 안 됩니다.

또한 opengraph-image.jpg, twitter-image.jpg, favicon.ico 같은 file-based metadata는 코드로 작성한 metadata보다 우선순위가 높습니다. OG 이미지가 바뀌지 않는다면 openGraph.images 코드만 보지 말고 같은 segment나 상위 segment의 특수 파일도 확인해야 합니다.

실제 코드에서 고치는 방법

수정은 문제를 가장 작게 재현한 뒤 적용하는 것이 좋습니다. 아래 예시는 실제 프로젝트 코드 전체가 아니라, 확인해야 할 핵심만 남긴 형태입니다.

export async function generateMetadata({ params }) {
  const { slug } = await params;
  const post = await getPost(slug);

  return {
    title: post.title,
    description: post.description,
    openGraph: {
      title: post.title,
      description: post.description,
      images: [post.ogImage],
    },
  };
}

generateMetadata는 렌더링 과정의 일부로 실행됩니다. prerender 가능한 페이지에서 동적 동작을 만들지 않으면 metadata는 초기 HTML에 포함되고, 동적 데이터가 필요하면 Next.js가 조건에 따라 metadata를 스트리밍할 수 있습니다. 단순 고정 문구라면 metadata 객체를 쓰고, route params나 게시글 데이터가 필요할 때만 generateMetadata로 분리합니다.

수정 후 확인할 체크리스트

Next.js metadata SEO 해결 체크리스트: generateMetadata와 head 확인 재크롤링 요청 기준

수정 후에는 개발 서버에서만 확인하지 말고 새로고침, 빌드, 실제 데이터 조건을 함께 봅니다. 조건이 하나만 달라져도 문제가 다시 보일 수 있기 때문입니다.

체크할 순서는 간단합니다. 먼저 공개 HTML의 <head>에 title, description, canonical, OG/Twitter 태그가 실제로 들어갔는지 봅니다. 그 다음 metadataBase, route segment 위치, file-based metadata 우선순위, 소셜 플랫폼 캐시를 확인합니다. 검색 결과 반영은 Google 재크롤링이 필요하므로 HTML 반영과 검색 노출을 구분합니다.

정리

Next.js metadata가 적용되지 않을 때는 한 가지 정답 코드보다 원인을 좁히는 순서가 더 중요합니다. Server Component export 위치, metadata/generateMetadata 선택, file-based metadata 우선순위, metadataBase, title template, 캐시를 차례대로 확인하세요. 자세한 기준은 generateMetadata, Metadata and OG images, Metadata Files, opengraph-image and twitter-image 문서를 함께 확인하면 됩니다.

이 글이 마음에 드세요?

RSS 피드를 구독하세요!

Next.js metadata가 적용되지 않을 때 확인할 7가지