og:title을 넣었는데 공유 미리보기가 비어 있던 이유

문제 발생

Open Graph 태그를 넣었는데 공유 미리보기에 아무것도 뜨지 않았습니다.

useHead({
  meta: [{ name: "og:title", content: post.title }],   // ❌ name
});

og: 계열은 name이 아니라 property인데, 오타처럼 조용히 지나가서 배포 후에야 알았습니다.

원인 분석

useHead는 head 태그를 다루는 기본 컴포저블입니다. 유연한 대신 무엇을 어디에 넣을지 전부 직접 적어야 하고, name과 property의 구분도 사람이 기억해야 합니다.

useSeoMeta는 그 위에 얹힌 SEO 전용 래퍼입니다. 공식 문서가 존재 이유를 그대로 적습니다 — name 대신 property를 쓰는 것 같은 흔한 실수와 오타를 피하도록 돕습니다. 완전한 타입 안전성을 제공하므로, Open Graph 태그에서 늘 헷갈리는 이 구분을 아예 신경 쓰지 않아도 됩니다.

해결 방안

1. SEO 메타는 useSeoMeta로 씁니다. 평평한 객체라 읽기도 쉽습니다.

<script setup>
const post = await getPost();

useSeoMeta({
  title: post.title,
  description: post.summary,
  ogTitle: post.title,
  ogDescription: post.summary,
  ogImage: post.coverUrl,
  ogType: "article",
  twitterCard: "summary_large_image",
});
</script>

2. 반응형 값은 함수로 넘깁니다. 값이 나중에 정해지는 경우 그대로 넘기면 그 시점 값으로 굳습니다.

useSeoMeta({
  title: () => post.value?.title ?? "",
});

3. useHead는 그 밖의 태그에 씁니다. canonical 링크, JSON-LD, htmlAttrs 같은 것들입니다.

useHead({
  link: [{ rel: "canonical", href: `https://meokko.com/notes/${slug}` }],
  htmlAttrs: { lang: "ko" },
});

4. 사이트 공통 값은 nuxt.config의 app.head에 둡니다. 다만 문서가 짚습니다 — 이 방법으로는 반응형 데이터를 제공할 수 없습니다. 파비콘, 기본 언어, 기본 제목처럼 변하지 않는 것만 둡니다.

5. 제목 템플릿으로 브랜드를 붙입니다. %s가 각 페이지 제목으로 치환됩니다. 페이지마다 접미사를 손으로 붙이지 않습니다.

app: {
  head: { titleTemplate: "%s · 개발 머꼬" },
}

6. 호출 위치는 setup 컨텍스트입니다. 두 컴포저블 모두 컴포넌트의 <script setup> 같은 setup 컨텍스트 안에서 불러야 합니다.

7. 컴포넌트 형태도 있습니다. 템플릿에서 선언적으로 쓰고 싶으면 <Title>, <Meta>, <Link> 같은 대문자 컴포넌트를 쓸 수 있습니다. 문서는 컴포저블을 권장합니다.

8. 메타 태그가 콘텐츠를 대신하지 않습니다. 초기 HTML에 실제 본문이 있어야 하고, 메타는 그것을 요약할 뿐입니다.

공식 문서

• Nuxt: SEO와 메타
• Nuxt: useSeoMeta