跳到主要内容
Nuxt 中文
开始使用

SEO 与 Meta

借助强大的 head 配置、composables 和组件，改善你的 Nuxt 应用的 SEO。

Nuxt 的 head 标签管理由 Unhead 提供支持。它提供了合理的默认值、多个强大的 composables 以及大量配置选项，用于管理你的应用的 head 和 SEO meta 标签。

Nuxt 配置（Nuxt Config）

在 nuxt.config.ts 中提供 app.head 属性，可以静态地自定义整个应用的 head。

这种方式不允许你提供响应式数据。我们建议在 app.vue 中使用 useHead()。

将那些不会发生变化的标签（例如你的站点默认标题、语言和 favicon）设置在这里是一个好习惯。

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      title: 'Nuxt', // default fallback title
      htmlAttrs: {
        lang: 'en',
      },
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      ],
    },
  },
})
当你设置 app.cdnURL 时，public/ 目录中的资源（包括 favicon.ico）会从这个 CDN 提供。Nuxt 会针对 cdnURL 解析公共资源，并回退到 app.baseURL。但是，像上面 href: '/favicon.ico' 这样的静态 app.head link 是一个字面量路径，不会针对 cdnURL 进行解析。要将 favicon 指向解析后的位置，请在 app.vue 中使用 useHead() 结合运行时配置来构建 href：
app/app.vue
<script setup lang="ts">
const { cdnURL, baseURL } = useRuntimeConfig().app
useHead({
  link: [
    { rel: 'icon', type: 'image/x-icon', href: `${cdnURL || baseURL}favicon.ico` },
  ],
})
</script>

你也可以在下方 Types 中提供列出的任意 key。

默认标签（Default Tags）

Nuxt 默认提供了一些标签，以确保你的网站开箱即可良好运行。

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

虽然大多数站点不需要覆盖这些默认值，但你可以使用带 key 的快捷方式来更新它们。

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      // update Nuxt defaults
      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 这两个 composables。

useSeoMeta

useSeoMeta composable 让你可以以对象的形式定义站点的 SEO meta 标签，并具备完整的类型安全。

这有助于你避免拼写错误和常见错误，例如误用 name 而非 property。

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>
阅读更多

组件（Components）

虽然我们在所有场景下都推荐使用 useHead，但你可能出于个人偏好更希望在模板中使用组件来定义 head 标签。

Nuxt 为此提供了以下组件：<Title>、<Base>、<NoScript>、<Style>、<Meta>、<Link>、<Body>、<Html> 和 <Head>。注意这些组件的首字母大写，以确保我们不会用到无效的原生 HTML 标签。

<Head> 和 <Body> 可以接受嵌套的 meta 标签（出于美观考虑），但这不会影响嵌套 meta 标签在最终 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> 组件中，这样标签的去重会更直观。

如果你需要在客户端与服务端边界之间复制标签，请在 <Head> 组件上应用一个 key 属性。

类型（Types）

以下是用于 useHead、app.head 和组件的非响应式类型。

Types
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）

所有属性都支持响应式，可以通过提供一个 computed 值、getter 或响应式对象来实现。

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

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

标题模板（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 Parameters）

你可以使用 templateParams 来在 titleTemplate 中提供除默认 %s 之外的额外占位符。这允许生成更具动态性的标题。

<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',
      // valid options are: 'head' | 'bodyClose' | 'bodyOpen'
      tagPosition: 'bodyClose',
    },
  ],
})
</script>

示例（Example）

配合 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>
阅读更多

动态标题（Dynamic Title）

在下面的示例中，titleTemplate 既可以设置为带有 %s 占位符的字符串，也可以设置为 function，从而允许你为 Nuxt 应用的每个路由更灵活地动态设置页面标题：

app/app.vue
<script setup lang="ts">
useHead({
  // as a string,
  // where `%s` is replaced with the title
  titleTemplate: '%s - Site Title',
})
</script>
app/app.vue
<script setup lang="ts">
useHead({
  // or as a function
  titleTemplate: (productCategory) => {
    return productCategory
      ? `${productCategory} - Site Title`
      : 'Site Title'
  },
})
</script>

nuxt.config 也作为一种替代方式来设置页面标题。但是，nuxt.config 不允许页面标题是动态的。因此，建议在 app.vue 文件中使用 titleTemplate 来添加动态标题，它会应用到 Nuxt 应用的所有路由上。

外部 CSS（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>