SEO and Meta

강력한 head 설정, composable, 컴포넌트로 Nuxt 앱의 SEO를 향상하세요.

Nuxt head 태그 관리는 Unhead에 의해 제공됩니다. 이는 합리적인 기본값과 여러 강력한 composable, 그리고 앱의 head 및 SEO 메타 태그를 관리하기 위한 다양한 설정 옵션을 제공합니다.

Nuxt Config

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에 나열된 키 중 어떤 것이든 제공할 수 있습니다.

Defaults Tags

일부 태그는 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 composable 함수는 반응형 입력을 지원하여, head 태그를 프로그래밍 방식으로 관리할 수 있게 해줍니다.

app/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 composable을 살펴보는 것을 권장합니다.

`useSeoMeta`

useSeoMeta composable을 사용하면, 사이트의 SEO 메타 태그를 완전한 타입 안전성을 가진 객체로 정의할 수 있습니다.

이는 property 대신 name을 사용하는 등의 오타 및 일반적인 실수를 방지하는 데 도움이 됩니다.

app/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 > 4 X > API > Composables > Use Seo Meta.

Components

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

Nuxt는 이 목적을 위해 <Title>, <Base>, <NoScript>, <Style>, <Meta>, <Link>, <Body>, <Html>, <Head> 컴포넌트를 제공합니다. 이 컴포넌트들이 대문자로 시작하는 점에 유의하여, 유효하지 않은 네이티브 HTML 태그를 사용하지 않도록 합니다.

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

app/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> 컴포넌트로 감싸는 것을 권장합니다.

Types

아래는 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를 참고하세요.

Features

Reactivity

계산된 값, 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>

Title 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'로 표시됩니다. 또한 null을 전달하여 기본값인 'Site Title'을 사용할 수도 있습니다.

Template Params

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

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

Body Tags

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

예를 들어:

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

Examples

With `definePageMeta`

app/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 > 4 X > Examples > Features > Meta Tags.

Read more in Docs > 4 X > Directory Structure > App > Pages > #page Metadata.

Dynamic Title

아래 예시에서, titleTemplate은 %s 플레이스홀더가 있는 문자열 또는 function으로 설정되며, 이를 통해 Nuxt 앱의 각 라우트에 대해 페이지 제목을 동적으로 설정하는 더 큰 유연성을 제공합니다:

app/app.vue

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

app/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 앱의 모든 라우트에 적용하는 것을 권장합니다.

External CSS

아래 예시는 useHead composable의 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>

Was this helpful?

Report an issue or Edit this page on GitHub

라우팅

Nuxt 파일 시스템 라우팅은 pages/ 디렉터리의 모든 파일에 대해 라우트를 생성합니다.

전환(Transitions)

Vue 또는 네이티브 브라우저 View Transitions로 페이지와 레이아웃 간 전환을 적용합니다.