nuxt logo

문서 번역(비공식)

Nuxt.js
Version:v3.17

SEO와 메타데이터

강력한 헤드 설정, composables, 컴포넌트를 활용하여 Nuxt 앱의 SEO를 개선합니다.

Nuxt의 헤드 태그 관리는 Unhead에 의해 구현됩니다. 이는 기본적으로 적절한 설정을 제공하며, 몇 가지 강력한 composables와 앱의 헤드 및 SEO 메타 태그를 관리하기 위한 다양한 설정 옵션을 제공합니다.

Nuxt 설정

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

이 방법으로는 반응형 데이터를 제공할 수 없습니다. 우리는 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 composable 함수는 반응형 입력을 지원하며, 프로그래밍 방식으로 헤드 태그를 관리할 수 있습니다.

app.vue
useHead({
  title: 'My App',
  meta: [
    { name: 'description', content: 'My amazing site.' }
  ],
  bodyAttrs: {
    class: 'test'
  },
  script: [ { innerHTML: 'console.log(\'Hello world\')' } ]
})

우리는 useHead와 useHeadSafe composables를 확인하는 것을 권장합니다.

useSeoMeta

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

이는 오타나 일반적인 실수를 피하는 데 도움이 됩니다. 예를 들어, property 대신 name을 사용하는 실수입니다.

app.vue
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',
})
이것도 참고 api > composables > use-seo-meta

컴포넌트

useHead의 사용이 모든 경우에 권장되지만, 템플릿 내에서 컴포넌트를 사용하여 헤드 태그를 정의하는 것이 특별히 선호되는 경우가 있습니다.

이 목적을 위해, 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> 컴포넌트로 래핑하는 것을 제안합니다. 태그는 직관적으로 제거됩니다.

타입

다음은 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를 참조하세요.

기능

반응성

모든 속성에 반응성이 지원됩니다. 계산된 값, 게터, 또는 반응형 객체를 제공함으로써 이를 실현합니다.

const description = ref('My amazing site.')

useHead({
  meta: [
    { name: 'description', content: description }
  ],
})

제목 템플릿

titleTemplate 옵션을 사용하여 사이트의 제목을 커스터마이즈하기 위한 동적 템플릿을 제공할 수 있습니다. 예를 들어, 모든 페이지의 제목에 사이트 이름을 추가할 수 있습니다.

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

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

useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
  }
})

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

템플릿 매개변수

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

useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} %separator %siteName` : '%siteName';
  },
  templateParams: {
    siteName: 'Site Title',
    separator: '-'
  }
})

바디 태그

적용 가능한 태그에 tagPosition: 'bodyClose' 옵션을 사용하여, 이를 <body> 태그의 마지막에 추가할 수 있습니다.

예를 들어:

useHead({
  script: [
    {
      src: 'https://third-party-script.com',
      // 유효한 옵션은: 'head' | 'bodyClose' | 'bodyOpen'
      tagPosition: 'bodyClose'
    }
  ]
})

예제

definePageMeta를 사용한 경우

pages/ 디렉토리 내에서는, definePageMeta와 useHead를 함께 사용하여 현재 경로에 기반한 메타데이터를 설정할 수 있습니다.

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

pages/some-page.vue
definePageMeta({
  title: 'Some Page'
})

그리고 레이아웃 파일에서는, 앞서 설정한 경로의 메타데이터를 사용할 수 있습니다:

layouts/default.vue
const route = useRoute()

useHead({
  meta: [{ property: 'og:title', content: `App Name - ${route.meta.title}` }]
})
샘플 코드 편집 및 미리보기examples > features > meta-tags
이것도 참고 guide > directory-structure > pages > #page-metadata

동적인 제목

다음 예제에서는, titleTemplate이 %s 플레이스홀더를 포함하는 문자열로 설정되었거나, 또는 function으로 설정되었습니다. 이를 통해 Nuxt 앱의 각 경로의 페이지 제목을 동적으로 설정할 수 있습니다.:

app.vue
useHead({
  // 문자열로서,
  // `%s`는 제목으로 대체됩니다
  titleTemplate: '%s - Site Title',
})
app.vue
useHead({
  // 또는 함수로서
  titleTemplate: (productCategory) => {
    return productCategory
      ? `${productCategory} - Site Title`
      : 'Site Title'
  }
})

페이지 제목 설정에는 nuxt.config도 사용됩니다. 그러나 nuxt.config에서는 페이지 제목을 동적으로 설정할 수 없습니다. 따라서, app.vue 파일 내에서 titleTemplate을 사용하여 동적인 제목을 추가하고, 이를 Nuxt 앱의 모든 경로에 적용하는 것을 권장합니다.

외부 CSS

다음 예제에서는, useHead composable의 link 속성이나 <Link> 컴포넌트를 사용하여 Google Fonts를 활성화하는 방법을 보여줍니다.

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

※이 페이지는 Nuxt.js 공식 문서의 비공식 번역 페이지입니다.

공식 문서의 해당 페이지는 여기 있습니다:
https://nuxt.com/docs/3.x/getting-started/seo-meta