🚀 Next.js 11장: Metadata API & SEO — 검색엔진이 사랑하는 앱 만들기

📋 개요

Metadata API로 OG 태그, 구조화 데이터, sitemap을 설정해 검색엔진에 최적화합니다.

📋 목차

📌 이 문서를 읽기 전에
🤔 왜 알아야 하는가
🏗️ 비유로 먼저 이해하기
🧩 Static Metadata — 변하지 않는 명함 🟢
🌱 Dynamic Metadata — 페이지마다 다른 얼굴 🟡
🖼️ OG 이미지 자동 생성 — opengraph-image.tsx 🟡
⚡ 고급 메타데이터: robots, sitemap, canonical 🔴
💥 에러 해결 카탈로그
🏁 이번에 배운 내용 총정리
📝 마무리 퀴즈
🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 (전체) / 핵심 파트만: 7분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

영철(신입): "어? 우리 서비스 카카오톡으로 링크 공유했더니 썸네일이 안 뜨고 URL만 덩그러니 나오네요. 그리고 구글에 검색해도 우리 서비스 이름이 안 나오고 'Vercel App'이라고만 뜨는데... 어떻게 고쳐요?"
영호(리드): "영철 님, <head> 태그 설정을 아직 안 하셨군요. Next.js Metadata API 를 쓰면 파일 하나 건드리지 않고도 각 페이지별 타이틀, 설명, OG 이미지를 정확히 세팅할 수 있어요. SEO는 선택이 아니라 서비스 가시성의 기본이에요."

🗺️ 이 문서의 흐름
정적 메타데이터 → 동적 메타데이터(페이지별) → OG 이미지 자동 생성 → robots/sitemap 고급 설정

🎯 이 문서를 다 읽으면 할 수 있는 것

layout.tsx에서 사이트 전체 기본 메타데이터를 선언할 수 있다
게시글 상세 페이지처럼 URL마다 다른 <title>, <description>을 자동으로 생성할 수 있다
카카오·슬랙 링크 공유 시 예쁜 썸네일이 뜨는 OG 이미지를 JSX 코드로 만들 수 있다

🤔 왜 알아야 하는가

리액트 SPA(Single Page Application)의 가장 큰 단점이 뭔지 알아? 바로 SEO(검색엔진 최적화) 였어.

SPA는 처음 서버에서 빈 HTML을 내려보내고, JavaScript가 로드된 뒤에야 화면을 채워. 그런데 구글 봇이 페이지를 크롤링하러 왔을 때, JS가 실행되기 전이라면 빈 껍데기만 보게 돼.

그래서 Next.js가 등장한 거야. 서버에서 완성된 HTML을 내려보내니까 봇도 내용을 볼 수 있지. 하지만 거기서 멈추면 안 돼. 봇이 "이 페이지가 뭔지"를 정확히 알려면 <title>, <description>, OG 태그들이 제대로 설정되어 있어야 해.

과거 Pages Router 시절엔 next/head로 각 페이지마다 <Head> 컴포넌트를 수동으로 달아줬어. 중복 코드가 넘쳐났고, 상속 개념도 없어서 관리가 지옥이었지. App Router의 Metadata API는 이 모든 걸 파일 기반 시스템으로 통합해버렸어.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?
상점들이 모인 쇼핑몰을 상상해봐. 각 가게 앞에는 간판이 있어.
구글 봇은 이 쇼핑몰을 순찰하는 안내원이야. 간판(메타데이터)을 읽고 "이 가게는 뭘 파는 곳이에요"라고 지도(검색 결과)에 기록해줘.
간판이 없거나 "Vercel App"이라고만 적혀 있으면, 안내원도 뭐라고 기록해야 할지 몰라서 그냥 주소만 적어두는 거야.

메타데이터는 페이지의 "정체성 명함"이야. layout.tsx는 건물 전체 안내판이고, page.tsx의 메타데이터는 각 층 간판인 거지. 상속 구조가 있어서 아래층 간판이 없으면 위층 건물 안내판으로 대체돼.

🧩 Static Metadata — 변하지 않는 명함 🟢

🎯 이 섹션을 읽고 나면:

layout.tsx에서 metadata 객체를 export해 사이트 전체 기본값을 설정할 수 있다

메타데이터의 상속 구조가 어떻게 작동하는지 설명할 수 있다

가장 단순한 방법부터 시작해. 그냥 metadata 객체를 export하면 끝이야.

// app/layout.tsx — 사이트 전체 기본값 설정
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: {
    // template: 하위 페이지에서 title을 설정하면 자동으로 " | 영수 커뮤니티" 가 붙음
    template: '%s | 영수 커뮤니티',
    // default: 하위 페이지에서 title을 설정 안 하면 이게 기본값
    default: '영수 커뮤니티 — 개발자 스터디 매칭',
  },
  description: '개발자들이 모여 함께 성장하는 스터디 매칭 플랫폼',
  // Open Graph: 카카오톡, 슬랙, 페이스북 등에서 링크 공유 시 미리보기 카드
  openGraph: {
    title: '영수 커뮤니티',
    description: '개발자 스터디 매칭 플랫폼',
    url: 'https://youngsu.community',
    siteName: '영수 커뮤니티',
    images: [
      {
        url: 'https://youngsu.community/og-image.png',
        width: 1200,
        height: 630,
      },
    ],
    locale: 'ko_KR',
    type: 'website',
  },
}
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  )
}

메타데이터 상속(Merging) 규칙:

Next.js는 루트 레이아웃부터 가장 깊은 페이지까지 메타데이터를 깊은 병합(deep merge) 해줘. 같은 키가 있으면 아래 계층 값이 이겨.

app/layout.tsx          → { title: { default: "영수 커뮤니티", template: "%s | 영수 커뮤니티" } }
  app/posts/layout.tsx  → { title: "게시판" }       → 최종: "게시판 | 영수 커뮤니티"
    app/posts/[id]/page.tsx → { title: "클로저 스터디" } → 최종: "클로저 스터디 | 영수 커뮤니티"

💡 한 줄로 기억하기
layout.tsx의 metadata는 유전자야. 아래 페이지는 덮어쓸 수 있고, 설정 안 하면 부모 것을 이어받아.

🌱 Dynamic Metadata — 페이지마다 다른 얼굴 🟡

🎯 이 섹션을 읽고 나면:

generateMetadata 함수로 URL 파라미터를 받아 동적으로 <title>, <description>을 생성할 수 있다

DB에서 데이터를 fetch해 메타데이터에 사용할 수 있다

🤔 잠깐, 먼저 생각해봐
게시글 상세 페이지 /posts/123와 /posts/456은 당연히 타이틀이 달라야 해.
어떻게 URL마다 다른 <title>을 자동으로 넣을 수 있을까?

정적 metadata 객체로는 한계가 있어. 게시글 ID에 따라 제목이 달라지는 동적 페이지에선 generateMetadata 함수를 써야 해.

// app/posts/[id]/page.tsx
 
import type { Metadata, ResolvingMetadata } from 'next'
 
// Props 타입은 page.tsx의 params와 동일하게
type Props = {
  params: Promise<{ id: string }>
}
 
// ✅ 비동기 함수로 선언 — DB 조회도 가능
export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata     // 부모 레이아웃 메타데이터에 접근 가능
): Promise<Metadata> {
  const { id } = await params
 
  // DB에서 게시글 데이터 fetch (Next.js가 자동으로 캐싱해줌 — 6장 참고)
  const post = await fetch(`https://api.youngsu.community/posts/${id}`, {
    next: { revalidate: 3600 },  // 1시간 캐싱
  }).then((res) => res.json())
 
  // 부모 레이아웃의 OG 이미지 배열에 내 이미지 추가하는 패턴
  const previousImages = (await parent).openGraph?.images || []
 
  return {
    title: post.title,                          // → "클로저 스터디 | 영수 커뮤니티"
    description: post.summary,                 // 게시글 요약
    openGraph: {
      title: post.title,
      description: post.summary,
      images: [
        `/posts/${id}/opengraph-image`,         // 동적 OG 이미지 (다음 섹션)
        ...previousImages,                      // 부모 이미지도 fallback으로 유지
      ],
    },
  }
}
 
export default async function PostPage({ params }: Props) {
  const { id } = await params
  // ...페이지 컴포넌트
}

영철이의 실수 패턴:

// ❌ 영철이의 순진한 코드 — 클라이언트 컴포넌트에서 메타데이터 설정하려는 시도
'use client'
import { useEffect } from 'react'
 
export default function PostPage() {
  useEffect(() => {
    // 이건 절대 안 돼! 봇은 JS 실행 전에 HTML을 읽어가거든
    document.title = '클로저 스터디'
  }, [])
  return <div>...</div>
}
 
// ✅ 영호가 고쳐준 코드
// → 위의 generateMetadata 함수 사용 (서버에서 실행되므로 봇도 읽을 수 있음)

➡️ 다음 섹션에서는: 메타데이터의 꽃, OG 이미지를 코드로 자동 생성하는 방법을 알아봐.

🖼️ OG 이미지 자동 생성 — `opengraph-image.tsx` 🟡

🎯 이 섹션을 읽고 나면:

opengraph-image.tsx 파일 하나로 JSX를 이미지로 변환하는 Dynamic OG Image를 만들 수 있다

URL 파라미터를 받아 게시글마다 다른 OG 이미지를 자동 생성할 수 있다

카카오톡이나 슬랙에서 링크를 공유할 때 예쁜 썸네일이 뜨는 거 봤지? 그게 OG(Open Graph) 이미지야.

Next.js는 opengraph-image.tsx라는 특수 파일을 통해 JSX로 이미지를 동적 생성하는 기능을 내장하고 있어. 내부적으로는 @vercel/og 라이브러리의 Satori 엔진이 JSX를 SVG → PNG로 변환해줘.

// app/posts/[id]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
 
// 이미지 크기 설정 (권장: 1200x630)
export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'
 
// params로 URL 파라미터를 받아 동적 이미지 생성
export default async function Image({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
 
  // DB에서 게시글 제목 가져오기 (서버에서 실행)
  const post = await fetch(`https://api.youngsu.community/posts/${id}`).then((r) => r.json())
 
  return new ImageResponse(
    // JSX로 이미지 레이아웃 구성
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        width: '100%',
        height: '100%',
        backgroundColor: '#0F172A',           // 다크 배경
        padding: '60px',
      }}
    >
      {/* 커뮤니티 로고 */}
      <div style={{ color: '#60A5FA', fontSize: 28, marginBottom: 24 }}>
        영수 커뮤니티
      </div>
      {/* 게시글 제목 — DB에서 가져온 동적 데이터 */}
      <div
        style={{
          color: '#F1F5F9',
          fontSize: 56,
          fontWeight: 'bold',
          textAlign: 'center',
          lineHeight: 1.3,
        }}
      >
        {post.title}
      </div>
    </div>,
    { ...size }
  )
}

결과: /posts/123/opengraph-image URL로 접근하면 해당 게시글 제목이 담긴 이미지가 PNG로 반환돼.

📖 용어: Satori — Vercel이 만든 JSX → SVG 변환 라이브러리야. 브라우저 없이 서버에서 HTML/CSS 레이아웃을 이미지로 렌더링해. 한자로 '깨달음'이라는 뜻.

💡 한 줄로 기억하기
opengraph-image.tsx는 "자동 포스터 제작기"야. 게시글 제목만 넣으면 링크 공유용 썸네일이 자동으로 만들어져.

⚡ 고급 메타데이터: robots, sitemap, canonical 🔴

🎯 이 섹션을 읽고 나면:

검색엔진 크롤링 범위를 robots.txt로 제어할 수 있다

sitemap.ts로 구글에 모든 페이지 URL을 자동 제출할 수 있다

🤖 robots.txt — 봇 출입 통제

// app/robots.ts — 자동으로 /robots.txt 생성
import type { MetadataRoute } from 'next'
 
export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      {
        userAgent: '*',        // 모든 봇
        allow: '/',            // 전체 허용
        disallow: [
          '/api/',             // API 경로는 봇 차단
          '/admin/',           // 관리자 페이지 차단
          '/my/',              // 내 정보 페이지 차단
        ],
      },
    ],
    sitemap: 'https://youngsu.community/sitemap.xml',
  }
}

🗺️ sitemap.xml — 구글에 페이지 목록 제출

// app/sitemap.ts — 자동으로 /sitemap.xml 생성
import type { MetadataRoute } from 'next'
 
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  // 정적 페이지
  const staticPages: MetadataRoute.Sitemap = [
    { url: 'https://youngsu.community', lastModified: new Date(), changeFrequency: 'daily', priority: 1 },
    { url: 'https://youngsu.community/posts', lastModified: new Date(), changeFrequency: 'hourly', priority: 0.9 },
  ]
 
  // 동적 게시글 페이지 — DB에서 전체 ID 목록 가져오기
  const posts = await fetch('https://api.youngsu.community/posts/ids').then((r) => r.json())
  const postPages: MetadataRoute.Sitemap = posts.map((id: string) => ({
    url: `https://youngsu.community/posts/${id}`,
    lastModified: new Date(),
    changeFrequency: 'weekly' as const,
    priority: 0.8,
  }))
 
  return [...staticPages, ...postPages]
}

🔗 canonical — 중복 URL 정리

같은 내용이 여러 URL에 존재할 때(예: 페이지네이션, 필터) 구글이 어떤 걸 원본으로 봐야 하는지 알려줘.

// app/posts/page.tsx
export const metadata: Metadata = {
  alternates: {
    canonical: 'https://youngsu.community/posts',   // 원본 URL 명시
  },
}

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐. 대부분 여기 있어.

❌ `generateMetadata` 에서 params를 await 안 해서 에러

언제 나오는가?

Error: params should be awaited before using its properties.

원인: Next.js 15부터 params가 Promise로 변경됨. await 없이 바로 쓰면 에러.

해결책:

// ❌ 이전 방식 (Next.js 14 이하)
export async function generateMetadata({ params }: { params: { id: string } }) {
  const id = params.id   // 에러!
}
 
// ✅ Next.js 15+ 방식
export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params  // await 필수
}

❌ OG 이미지에서 폰트가 깨져서 한글이 네모로 표시됨

원인: Satori 엔진은 기본 폰트가 영문만 지원해. 한글은 별도 폰트 파일을 제공해야 해.

해결책:

// app/posts/[id]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
 
// 한글 폰트 파일 로드 (public 폴더에 미리 넣어둬야 함)
const fontData = await fetch(
  new URL('../../../../public/fonts/Noto_Sans_KR.ttf', import.meta.url)
).then((res) => res.arrayBuffer())
 
return new ImageResponse(
  <div>...</div>,
  {
    ...size,
    fonts: [
      { name: 'Noto Sans KR', data: fontData, style: 'normal' },
    ],
  }
)

❌ 메타데이터가 클라이언트 컴포넌트에서 작동 안 함

원인: metadata export와 generateMetadata는 서버 컴포넌트에서만 동작해. 'use client' 파일에서 export 하면 무시됨.

해결책: 메타데이터는 항상 서버 컴포넌트 파일(layout.tsx, page.tsx)에서 export해야 해. 클라이언트 로직이 필요하면 컴포넌트를 분리해.

🏁 이번에 배운 내용 총정리

오늘 배운 핵심을 한눈에 정리해볼까? SEO 문제가 생길 때 이것만 봐도 돼.

📋 메타데이터 설정 패턴

상황	방법	파일 위치
사이트 전체 기본값	`export const metadata`	`app/layout.tsx`
특정 섹션 기본값	`export const metadata`	`app/[section]/layout.tsx`
동적 페이지 (DB 조회)	`export async function generateMetadata`	`app/[section]/[id]/page.tsx`
링크 공유 썸네일	`opengraph-image.tsx`	`app/[section]/[id]/opengraph-image.tsx`
봇 접근 제어	`export default function robots()`	`app/robots.ts`
구글 페이지 목록	`export default async function sitemap()`	`app/sitemap.ts`

⚠️ 절대 하지 말 것

상황	❌ 나쁜 예	✅ 좋은 예
동적 타이틀	`useEffect(() => { document.title = ... })`	`generateMetadata` 함수
클라이언트에서 메타데이터	`'use client'` 파일에 `metadata` export	서버 컴포넌트 파일에 export
한글 OG 이미지 폰트	기본 폰트 그대로 사용	한글 TTF 파일 명시적으로 제공

📝 마무리 퀴즈

Q1. 다음 중 App Router의 Metadata API에 대한 설명으로 틀린 것은?

A) layout.tsx에서 metadata를 export하면 하위 페이지에 기본값으로 적용된다
B) generateMetadata는 클라이언트 컴포넌트에서도 사용할 수 있다
C) opengraph-image.tsx는 JSX를 PNG 이미지로 변환해준다
D) 동적 라우트에서 DB 데이터를 기반으로 <title>을 생성할 수 있다

✅ 정답: B — generateMetadata와 metadata export는 서버 컴포넌트 전용이야.

오답 해설:

A — 맞아. layout.tsx의 메타데이터는 하위로 상속(병합)됨

C — 맞아. opengraph-image.tsx는 Satori 엔진으로 JSX → PNG 변환

D — 맞아. generateMetadata는 async 함수라 DB 조회 가능

📌 핵심 기억법: metadata는 서버에서만! 클라이언트 컴포넌트는 손대지 마.

Q2. 아래 빈칸을 채워보자.

루트 레이아웃에서 title.template을 '%s | 영수 커뮤니티'로 설정했을 때,
게시글 페이지에서 title: '클로저 스터디'를 설정하면 <title> 태그의 최종 값은?

✅ 정답: 클로저 스터디 | 영수 커뮤니티

해설: %s 자리에 하위 페이지의 title 값이 들어가는 템플릿 패턴이야.

📌 핵심 기억법: %s는 자리표시자(placeholder). "여기에 페이지 이름 들어와" 라는 뜻.

Q3. 친구에게 설명한다면?

OG 이미지가 왜 SEO에서 중요한지, 그리고 Next.js에서 어떻게 자동 생성하는지 비유를 하나 써서 설명해봐.

예시 답변:

"OG 이미지는 링크 공유용 책 표지야. 제목만 있는 책이랑 멋진 표지가 있는 책 중에 어떤 걸 더 클릭하겠어? Next.js의 opengraph-image.tsx는 책 표지 인쇄기야. 게시글 제목만 넣으면 표지를 자동으로 뽑아줘."

🐣 영철이의 퇴근 일기

오늘은 우리 서비스의 '간판'을 다는 날이었어. 구글에 우리 서비스 이름을 검색해도 안 나와서 속상했는데, 영호 리드 님이 알려주신 'Metadata API' 로 사이트의 정체성을 명확하게 알려줬거든!

💡 오늘의 교훈: "메타데이터는 서비스의 명함이다. 봇과 사람이 우리 서비스를 잘 찾을 수 있게 친절한 간판(SEO)을 달아주자."

특히 카카오톡으로 링크를 보냈을 때 게시글 제목이 담긴 예쁜 썸네일(Dynamic OG Image)이 뙇! 뜨는 걸 보고 정말 감동했어. 단순히 코드를 짜는 걸 넘어, 세상에 우리 서비스를 어떻게 보여줄지 설계하는 게 얼마나 중요한지 깨달았어. 오늘 정말 고생한 나 자신에게 맛있는 아이스크림 하나 선물해야지. 내일은 더 '검색 친화적인' 멋진 페이지를 만들어볼 거야! 🐣