Headless CMS 아키텍처와 SEO 빌드 파이프라인 (Sanity, Strapi)

Headless CMS는 콘텐츠 관리(백엔드)와 콘텐츠 표시(프론트엔드)를 완전히 분리한 아키텍처입니다. WordPress 같은 전통 CMS는 콘텐츠 관리와 HTML 렌더링이 하나의 시스템에서 이루어지지만, Headless CMS는 콘텐츠를 API(REST/GraphQL)로만 제공하고 프론트엔드는 별도의 프레임워크(Next.js, Astro 등)로 구축합니다.

전통 CMS vs Headless CMS 비교

Headless CMS의 SEO 장점과 위험

• 장점: 최신 프레임워크의 SSG/ISR로 Core Web Vitals 최상급 달성 가능. CDN 배포로 극도로 빠른 TTFB. 멀티 채널(웹, 앱, IoT)에 동일 콘텐츠 재사용
• 위험: SEO 설정이 "자동으로 되지 않음". 메타데이터·사이트맵·구조화 데이터·canonical 등 모든 SEO 요소를 프론트엔드에서 직접 구현해야 함. 구현 누락 시 SEO가 전통 CMS보다 나빠질 수 있음

Headless CMS에서 SEO를 성공적으로 구현하려면 CMS 스키마 설계 단계부터 SEO 필드를 고려해야 합니다.

CMS 스키마에 포함해야 할 SEO 필드

Sanity에서 재사용 가능한 SEO 오브젝트

// sanity/schemas/objects/seo.ts
export default defineType({
  name: 'seo',
  title: 'SEO 설정',
  type: 'object',
  fields: [
    defineField({ name: 'title', title: 'SEO 제목', type: 'string',
      description: '검색 결과에 표시될 제목 (50~60자)', validation: (Rule) => Rule.max(60) }),
    defineField({ name: 'description', title: 'SEO 설명', type: 'text', rows: 3,
      description: '검색 결과에 표시될 설명 (120~160자)', validation: (Rule) => Rule.max(160) }),
    defineField({ name: 'ogImage', title: 'OG 이미지', type: 'image',
      description: '1200×630px 권장' }),
    defineField({ name: 'noIndex', title: '검색엔진 제외', type: 'boolean', initialValue: false }),
  ],
});

// 글(Post) 스키마에서 사용
defineField({ name: 'seo', title: 'SEO 설정', type: 'seo' })

프론트엔드에서 메타데이터 매핑 (Next.js)

// app/blog/[slug]/page.tsx
import { getPost } from '@/sanity/queries';

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

  return {
    title: post.seo?.title || post.title,
    description: post.seo?.description || post.excerpt,
    openGraph: {
      images: [{ url: post.seo?.ogImage?.url || post.mainImage?.url }],
    },
    robots: post.seo?.noIndex ? { index: false } : undefined,
    alternates: { canonical: `https://example.com/blog/${slug}` },
  };
}

CMS 선택 시 SEO 관점 체크리스트

• ☑ SEO 메타데이터 필드를 자유롭게 정의할 수 있는가?
• ☑ 이미지 변환 API가 있어 WebP/AVIF 최적화가 가능한가?
• ☑ Webhook을 지원하여 ISR On-Demand Revalidation이 가능한가?
• ☑ 다국어(locale) 지원이 있어 hreflang 구현이 용이한가?
• ☑ 발행일(publishedAt)·수정일(updatedAt)을 자동 관리하는가?
• ☑ 리치 텍스트 편집기가 Heading 구조(H2~H4)를 올바르게 출력하는가?

Headless CMS 기반 동적 사이트맵 (Next.js)

// app/sitemap.ts
import { getAllPosts, getAllPages } from '@/sanity/queries';

export default async function sitemap() {
  const posts = await getAllPosts(); // Sanity GROQ 쿼리
  const pages = await getAllPages();

  const blogEntries = posts.map((post) => ({
    url: `https://example.com/blog/${post.slug}`,
    lastModified: new Date(post._updatedAt),  // CMS 자체 수정일
    changeFrequency: 'weekly',
    priority: 0.7,
  }));

  const pageEntries = pages.map((page) => ({
    url: `https://example.com/${page.slug}`,
    lastModified: new Date(page._updatedAt),
    priority: 0.8,
  }));

  return [
    { url: 'https://example.com', priority: 1.0, lastModified: new Date() },
    ...pageEntries,
    ...blogEntries,
  ];
}

Webhook → On-Demand ISR 재검증 흐름

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const body = await req.json();
  const secret = req.headers.get('x-webhook-secret');

  if (secret !== process.env.SANITY_WEBHOOK_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // Sanity Webhook payload에서 변경된 문서의 slug 추출
  const slug = body?.slug?.current;
  if (slug) {
    revalidatePath(`/blog/${slug}`);
    return NextResponse.json({ revalidated: true, slug });
  }

  // slug 없으면 전체 재검증
  revalidatePath('/', 'layout');
  return NextResponse.json({ revalidated: true, full: true });
}

SEO 친화적 콘텐츠 모델 설계 5원칙

1. SEO 필드를 1급 시민으로
   • SEO 메타데이터를 "선택적 추가"가 아닌 콘텐츠 스키마의 필수 필드로 설계
   • 유효성 검사(Validation)로 제목 60자·설명 160자 제한 자동 적용
   • 편집자가 SEO 필드를 비워두면 본문에서 자동 추출하는 폴백 로직 구현
2. 컨텐츠 참조(Reference)로 관계 표현
   • 작성자(Author), 카테고리(Category), 태그(Tag)를 독립 문서로 만들고 참조
   • 프론트엔드에서 JSON-LD의 author, articleSection 등에 자동 매핑
   • 내부 링크도 참조로 표현하면 "관련 글" 자동 생성 → 토픽 클러스터 구축
3. 리치 텍스트의 Heading 구조 보장
   • CMS 리치 텍스트 편집기에서 H1 사용을 금지하고 H2~H4만 허용 (H1은 페이지 제목)
   • Sanity Portable Text: 커스텀 블록 타입에서 heading 스타일 제한 가능
   • 리치 텍스트의 이미지에 alt 텍스트 필수 입력 설정
4. slug 자동 생성 + 수동 편집
   • 제목에서 slug를 자동 생성하되 편집자가 SEO에 최적화된 slug로 수정 가능하게
   • 이미 발행된 콘텐츠의 slug 변경 시 301 리다이렉트 자동 생성 로직 구축
5. 다국어 콘텐츠 구조화
   • 다국어 지원 시 locale별 독립 문서 또는 필드 레벨 번역 중 선택
   • hreflang 태그는 프론트엔드에서 CMS locale 데이터를 기반으로 자동 생성

편집자 SEO 가이드라인

Headless CMS에서는 Yoast 같은 실시간 SEO 코칭 도구가 없으므로, 편집자를 위한 SEO 가이드라인을 별도로 만들어야 합니다.