SEO 및 메타

강력한 head 설정, 컴포저블 및 컴포넌트로 Nuxt 앱의 SEO를 향상시키세요.

Nuxt의 head 태그 관리는 Unhead로 구동됩니다. 이는 합리적인 기본값, 여러 강력한 컴포저블, 그리고 앱의 head 및 SEO 메타 태그를 관리할 수 있는 다양한 설정 옵션을 제공합니다.

Nuxt 설정

nuxt.config.ts에서 app.head 속성을 제공하면 전체 앱의 head를 정적으로 커스터마이즈할 수 있습니다.

이 방법은 반응형 데이터를 제공할 수 없습니다. app.vue에서 useHead() 사용을 권장합니다.

변경되지 않는 사이트 기본 제목, 언어, 파비콘과 같은 태그를 이곳에 설정하는 것이 좋은 관례입니다.

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      title: 'Nuxt', // 기본 대체 제목
      htmlAttrs: {
        lang: 'en',
      },
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      ]
    }
  }
})

아래 Types에 나열된 키 중 어떤 것이든 제공할 수 있습니다.

기본 태그

일부 태그는 Nuxt에서 기본적으로 제공되어 웹사이트가 바로 잘 작동하도록 보장합니다.

viewport: width=device-width, initial-scale=1
charset: utf-8

대부분의 사이트는 이러한 기본값을 재정의할 필요가 없지만, 키 단축키를 사용하여 업데이트할 수 있습니다.

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      // Nuxt 기본값 업데이트
      charset: 'utf-16',
      viewport: 'width=device-width, initial-scale=1, maximum-scale=1',
    }
  }
})

`useHead`

useHead 컴포저블 함수는 반응형 입력을 지원하여 head 태그를 프로그래밍적으로 관리할 수 있습니다.

app.vue

<script setup lang="ts">
useHead({
  title: 'My App',
  meta: [
    { name: 'description', content: 'My amazing site.' }
  ],
  bodyAttrs: {
    class: 'test'
  },
  script: [ { innerHTML: 'console.log(\'Hello world\')' } ]
})
</script>

useHead 및 useHeadSafe 컴포저블을 참고하는 것을 권장합니다.

`useSeoMeta`

useSeoMeta 컴포저블을 사용하면 사이트의 SEO 메타 태그를 타입 안정성이 보장된 객체로 정의할 수 있습니다.

이렇게 하면 name 대신 property를 사용하는 등 오타나 일반적인 실수를 방지할 수 있습니다.

app.vue

<script setup lang="ts">
useSeoMeta({
  title: 'My Amazing Site',
  ogTitle: 'My Amazing Site',
  description: 'This is my amazing site, let me tell you all about it.',
  ogDescription: 'This is my amazing site, let me tell you all about it.',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image',
})
</script>

Read more in Docs > API > Composables > Use Seo Meta.

컴포넌트

모든 경우에 useHead 사용을 권장하지만, 템플릿에서 컴포넌트를 사용하여 head 태그를 정의하는 것을 선호할 수도 있습니다.

Nuxt는 이 목적을 위해 다음 컴포넌트를 제공합니다: <Title>, <Base>, <NoScript>, <Style>, <Meta>, <Link>, <Body>, <Html>, <Head>. 이 컴포넌트들의 대문자 표기법에 주의하세요. 이는 잘못된 네이티브 HTML 태그 사용을 방지합니다.

<Head>와 <Body>는 (미관상 이유로) 중첩된 메타 태그를 허용하지만, 이는 최종 HTML에서 중첩된 메타 태그가 어디에 렌더링되는지에는 영향을 주지 않습니다.

app.vue

<script setup lang="ts">
const title = ref('Hello World')
</script>

<template>
  <div>
    <Head>
      <Title>{{ title }}</Title>
      <Meta name="description" :content="title" />
      <Style>
      body { background-color: green; }
      </Style>
    </Head>

    <h1>{{ title }}</h1>
  </div>
</template>

컴포넌트는 <Head> 또는 <Html> 컴포넌트로 감싸는 것이 태그가 더 직관적으로 dedupe(중복 제거)되므로 권장됩니다.

타입

아래는 useHead, app.head, 컴포넌트에 사용되는 비반응형 타입입니다.

interface MetaObject {
  title?: string
  titleTemplate?: string | ((title?: string) => string)
  templateParams?: Record<string, string | Record<string, string>>
  base?: Base
  link?: Link[]
  meta?: Meta[]
  style?: Style[]
  script?: Script[]
  noscript?: Noscript[];
  htmlAttrs?: HtmlAttributes;
  bodyAttrs?: BodyAttributes;
}

더 자세한 타입은 @unhead/vue에서 확인할 수 있습니다.

기능

반응성

모든 속성에서 계산된 값, getter, 반응형 객체를 제공하여 반응성을 지원합니다.

<script setup lang="ts">
const description = ref('My amazing site.')

useHead({
  meta: [
    { name: 'description', content: description }
  ],
})
</script>

<script setup lang="ts">
const description = ref('My amazing site.')

useSeoMeta({
  description
})
</script>

<script setup lang="ts">
const description = ref('My amazing site.')
</script>

<template>
  <div>
    <Meta name="description" :content="description" />
  </div>
</template>

제목 템플릿

titleTemplate 옵션을 사용하여 사이트 제목을 동적으로 커스터마이즈할 수 있습니다. 예를 들어, 모든 페이지 제목에 사이트 이름을 추가할 수 있습니다.

titleTemplate는 %s가 제목으로 대체되는 문자열이거나 함수가 될 수 있습니다.

함수를 사용하고 싶다면(완전한 제어를 위해), 이는 nuxt.config에서 설정할 수 없습니다. 대신 모든 페이지에 적용되도록 app.vue 파일 내에서 설정하는 것을 권장합니다:

<script setup lang="ts">
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
  }
})
</script>

이제 사이트의 다른 페이지에서 useHead로 제목을 My Page로 설정하면, 브라우저 탭에 'My Page - Site Title'로 표시됩니다. 기본값으로 'Site Title'을 사용하려면 null을 전달할 수도 있습니다.

템플릿 파라미터

titleTemplate에서 기본 %s 외에 추가 플레이스홀더를 제공하려면 templateParams를 사용할 수 있습니다. 이를 통해 더 동적인 제목 생성이 가능합니다.

<script setup lang="ts">
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} %separator %siteName` : '%siteName';
  },
  templateParams: {
    siteName: 'Site Title',
    separator: '-'
  }
})
</script>

Body 태그

적용 가능한 태그에 tagPosition: 'bodyClose' 옵션을 사용하여 <body> 태그 끝에 추가할 수 있습니다.

예시:

<script setup lang="ts">
useHead({
  script: [
    {
      src: 'https://third-party-script.com',
      // 유효한 옵션: 'head' | 'bodyClose' | 'bodyOpen'
      tagPosition: 'bodyClose'
    }
  ]
})
</script>

예시

`definePageMeta`와 함께

pages/ 디렉토리 내에서, 현재 라우트에 따라 메타데이터를 설정하기 위해 definePageMeta와 useHead를 함께 사용할 수 있습니다.

예를 들어, 먼저 현재 페이지 제목을 설정할 수 있습니다(이것은 매크로를 통해 빌드 타임에 추출되므로 동적으로 설정할 수 없습니다):

pages/some-page.vue

<script setup lang="ts">
definePageMeta({
  title: 'Some Page'
})
</script>

그리고 레이아웃 파일에서, 이전에 설정한 라우트의 메타데이터를 사용할 수 있습니다:

layouts/default.vue

<script setup lang="ts">
const route = useRoute()

useHead({
  meta: [{ property: 'og:title', content: `App Name - ${route.meta.title}` }]
})
</script>

Read and edit a live example in Docs > Examples > Features > Meta Tags.

Read more in Docs > Guide > Directory Structure > Pages > #page Metadata.

동적 제목

아래 예시에서, titleTemplate는 %s 플레이스홀더가 있는 문자열 또는 function으로 설정되어, Nuxt 앱의 각 라우트에 대해 페이지 제목을 동적으로 설정할 수 있습니다:

app.vue

<script setup lang="ts">
useHead({
  // 문자열로,
  // 여기서 `%s`는 제목으로 대체됩니다
  titleTemplate: '%s - Site Title',
})
</script>

app.vue

<script setup lang="ts">
useHead({
  // 또는 함수로
  titleTemplate: (productCategory) => {
    return productCategory
      ? `${productCategory} - Site Title`
      : 'Site Title'
  }
})
</script>

nuxt.config도 페이지 제목을 설정하는 대안으로 사용됩니다. 하지만, nuxt.config에서는 페이지 제목을 동적으로 설정할 수 없습니다. 따라서, app.vue 파일에서 titleTemplate을 사용하여 동적 제목을 추가하는 것이 권장되며, 이는 Nuxt 앱의 모든 라우트에 적용됩니다.

외부 CSS

아래 예시는 useHead 컴포저블의 link 속성이나 <Link> 컴포넌트를 사용하여 Google Fonts를 활성화하는 방법을 보여줍니다:

<script setup lang="ts">
useHead({
  link: [
    {
      rel: 'preconnect',
      href: 'https://fonts.googleapis.com'
    },
    {
      rel: 'stylesheet',
      href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
      crossorigin: ''
    }
  ]
})
</script>

<template>
  <div>
    <Link rel="preconnect" href="https://fonts.googleapis.com" />
    <Link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" crossorigin="" />
  </div>
</template>