SEO和元数据

使用强大的 head 配置、composables 和组件改善您的 Nuxt 应用程序的 SEO。

Nuxt 的 head 标签管理由 Unhead 提供支持。它提供了合理的默认设置、几个强大的 composables 和众多的配置选项，用于管理您的应用程序的 head 和 SEO 元标签。

Nuxt 配置

在您的 nuxt.config.ts 中提供 app.head 属性，允许您静态地自定义整个应用程序的 head。

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

在这里设置不会更改的标签（例如您的网站标题默认值、语言和网站图标）是一个好习惯。

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' },
      ]
    }
  }
})

您还可以提供类型中列出的任何键。

默认标签

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

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

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

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.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。

在 Nuxt 3 中，useHead 和 useHeadSafe 都是用于动态管理 HTML Head 标签的组合式函数，但它们在安全性和属性支持范围上有本质区别，以下是核心对比：核心差异对比

特性	`useHead`	`useHeadSafe`
安全性	❌ 无内置过滤，需手动防范 XSS	✅ 自动过滤非安全属性（白名单机制）
适用场景	完全可控的静态内容	用户输入或第三方数据等不可信内容
属性支持范围	无限制，支持任意 HTML 属性	仅限白名单内安全属性（如 `href`、`content`）
风险示例	允许 `innerHTML` 执行恶意脚本	忽略危险属性（如 `innerHTML`、`http-equiv`）

功能详解

useHead：灵活但需谨慎
- 无安全性限制：可设置任意属性，包括 innerHTML、onload 等高风险属性。
- 示例风险代码：
```
useHead({
  script: [{
    id: 'xss-script',
    innerHTML: 'alert("XSS攻击")' // 客户端会执行此脚本！
  }]
})
```
  此代码会导致 alert 弹窗，实际攻击中可能窃取用户数据。
- 适用场景：仅当内容完全可控时使用（如硬编码的静态资源）。

useHeadSafe：自动过滤危险属性

白名单机制：仅允许预定义的安全属性，其他属性会被忽略：

const WhitelistAttributes = {
  link: ['href', 'rel', 'type'],      // 仅允许这些属性
  meta: ['name', 'content', 'charset'],
  script: ['type', 'textContent'],    // 禁止 innerHTML
  bodyAttrs: ['class', 'style']       // 仅允许 class/style
}

安全处理示例：

useHeadSafe({
  script: [{
    innerHTML: 'alert("XSS攻击")'  // 此属性被忽略，不会渲染到 HTML
  }]
})

输出结果：<script></script>（无危险代码）。

适用场景：用户评论、动态生成的 SEO 描述等不可信内容。

安全漏洞案例分析
假设需要渲染用户提交的 og:description：

// 危险写法（useHead）
useHead({
  meta: [{
    property: 'og:description',
    content: userInput // 若含 <script> 则引发 XSS
  }]
})

// 安全写法（useHeadSafe）
useHeadSafe({
  meta: [{
    property: 'og:description',
    content: userInput, // 自动过滤 HTML 标签
    onload: 'malicious()' // 此属性被忽略
  }]
})

结果对比：
- useHead 可能输出：<meta property="og:description" content="<script>stealData()</script>">
- useHeadSafe 输出：<meta property="og:description" content="<script>stealData()</script>">（转义为纯文本）。

`useSeoMeta`

useSeoMeta composable 允许您将站点的 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> 组件中，因为标签将被更直观地去重。

类型

以下是用于 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 将标题设置为 我的页面，则浏览器选项卡中的标题将显示为“我的页面 - 网站标题”。您也可以传递 null 以默认为 “网站标题”。

模板参数

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

<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',
      // valid options are: '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 more in Docs > Guide > Directory Structure > Pages > #page Metadata.

动态标题

在下面的示例中，titleTemplate 设置为一个带有 %s 占位符的字符串或一个 function，这允许在为您的 Nuxt 应用程序的每个路由动态设置页面标题时具有更大的灵活性：

app.vue

<script setup lang="ts">
useHead({
  // as a string,
  // where `%s` is replaced with the title
  titleTemplate: '%s - Site Title',
})
</script>

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

下面的示例演示了如何使用 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>

路由

Nuxt 的文件系统路由会为 pages/ 目录中的每个文件创建一个路由。

过渡

使用 Vue 或原生浏览器视图过渡在页面和布局之间应用过渡效果。