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

학습 목표·선수 지식: metadata가 사라진 위치를 일곱 단계로 좁힙니다. 선수 지식: layout·page·HTML head.

1. 실제 경로의 서버 파일인가요?

app/layout.tsx 또는 해당 page.tsx의 export인지 확인합니다. use client 파일에서 metadata를 내보내면 빌드 오류입니다. 인터랙션 컴포넌트를 별도 파일로 옮깁니다.

2. 두 export가 충돌하나요?

같은 segment에 metadata와 generateMetadata를 함께 내보내지 않습니다. 고정 제목은 객체, 데이터 의존 제목은 함수 하나를 선택합니다.

3. params와 데이터가 올바른가요?

generateMetadata에서 먼저 await params로 slug를 풉니다. 다른 slug 두 개를 직접 열어 서로 다른 제목이 나오는지 확인합니다. 없는 데이터는 notFound로 처리하고 200 본문에 임의 제목을 만들지 않습니다.

4. URL 기준이 맞나요?

metadataBase와 canonical·OG 이미지의 최종 절대 URL을 확인합니다. Preview 도메인이 production canonical에 섞이지 않도록 공개 도메인을 지정합니다.

5. 특수 파일이 덮어쓰나요?

같은 경로와 상위 폴더의 opengraph-image·twitter-image·favicon 파일을 찾습니다. 파일 기반 metadata가 코드 설정보다 우선할 수 있습니다. 이미지 주소 자체와 이미지 HTTP 응답을 따로 봅니다.

6. 병합과 제목 템플릿이 의도한 결과인가요?

중첩 openGraph 객체는 깊은 병합이 아니므로 자식이 선언한 객체에서 필요한 값을 명시합니다. title.template은 하위 segment에 적용되며 같은 segment의 page에는 적용되지 않습니다. 정확한 제목이 필요하면 title.absolute로 상위 템플릿을 우회합니다.

7. 어떤 응답과 캐시를 검사했나요?

사전 렌더링 페이지와 동적 스트리밍 페이지를 나눕니다. 동적 metadata는 초기 UI 뒤 응답 body에 올 수 있으므로 head만 추출한 검사는 거짓 누락을 만들 수 있습니다. 전체 document 응답, hydration 후 DOM, HTML 제한 봇용 응답을 구분해 기록합니다. HTML 수정 반영, 소셜 재스크랩, 실제 검색 결과 갱신은 서로 다른 단계입니다.

터미널 · 진단 명령

curl -sS -D headers.txt -o full-response.html https://example.com/posts/sample
curl -sS -A "Twitterbot" -o bot-response.html https://example.com/posts/sample

위 명령의 도메인은 자신의 공개 테스트 URL로 바꾸세요. 봇 User-Agent를 흉내 낸 HTTP 확인은 검색 엔진의 실제 렌더·색인 결과를 증명하지 않습니다.

관련 학습 자료

• Next.js App Router metadata 가이드
• Next.js SEO 완전 가이드
• generateMetadata
• Metadata and OG images
• Metadata Files
• opengraph-image and twitter-image

공식 기준과 확인 범위

확인일: 2026-09-12. API 설명은 Next.js 16 App Router 기준이며 과거 릴리스 글은 본문의 태그 범위를 유지합니다. 부분 API 코드는 기존 프로젝트에 통합하는 예시입니다.

• https://nextjs.org/docs/app/api-reference/functions/generate-metadata

공식 자료 재확인: 2026-09-12. 이 글의 실행하지 않은 브라우저/배포 점검은 독자 확인 과제로 구분합니다.