generateMetadata

你可以使用 metadata 对象或 generateMetadata 函数来定义元数据。

`metadata` 对象

要定义静态元数据，从 layout.js 或 page.js 文件导出 Metadata 对象。

TypeScript

layout.tsx | page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: '...',
  description: '...',
}

export default function Page() {}

JavaScript

layout.js | page.js
export const metadata = {
  title: '...',
  description: '...',
}

export default function Page() {}

有关支持的选项的完整列表，请参阅元数据字段。

`generateMetadata` 函数

动态元数据依赖于动态信息，例如当前路由参数、外部数据或父段中的 metadata，可以通过导出一个返回 Metadata 对象的 generateMetadata 函数来设置。

TypeScript
JavaScript

app/products/[id]/page.tsx
import type { Metadata, ResolvingMetadata } from 'next'

type Props = {
  params: Promise<{ id: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  // 读取路由参数
  const { id } = await params

  // 获取数据
  const product = await fetch(`https://.../${id}`).then((res) => res.json())

  // 可选地访问和扩展（而不是替换）父元数据
  const previousImages = (await parent).openGraph?.images || []

  return {
    title: product.title,
    openGraph: {
      images: ['/some-specific-page-image.jpg', ...previousImages],
    },
  }
}

export default function Page({ params, searchParams }: Props) {}

app/products/[id]/page.js
export async function generateMetadata({ params, searchParams }, parent) {
  // 读取路由参数
  const { id } = await params

  // 获取数据
  const product = await fetch(`https://.../${id}`).then((res) => res.json())

  // 可选地访问和扩展（而不是替换）父元数据
  const previousImages = (await parent).openGraph?.images || []

  return {
    title: product.title,
    openGraph: {
      images: ['/some-specific-page-image.jpg', ...previousImages],
    },
  }
}

export default function Page({ params, searchParams }) {}

提示：

元数据可以添加到 layout.js 和 page.js 文件中。

Next.js 会自动解析元数据，并为页面创建相关的 <head> 标签。

metadata 对象和 generateMetadata 函数的导出仅在服务端组件中支持。

你不能从同一路由段导出 metadata 对象和 generateMetadata 函数。

generateMetadata 中的 fetch 请求会自动进行记忆化，以便在 generateMetadata、generateStaticParams、布局、页面和服务端组件之间共享相同的数据。

解析 generateMetadata 是渲染页面的一部分。如果页面可以预渲染，并且 generateMetadata 不引入动态行为，则其结果将包含在页面的初始 HTML 中。

如果 fetch 不可用，可以使用 React cache。

基于文件的元数据优先级更高，将覆盖 metadata 对象和 generateMetadata 函数。

参考

参数

generateMetadata 函数接受以下参数：

props - 包含当前路由参数的对象：
- params - 包含从根段到调用 generateMetadata 的段的动态路由参数对象。示例：
  
  路由 URL params
  app/shop/[slug]/page.js /shop/1 { slug: '1' }
  app/shop/[tag]/[item]/page.js /shop/1/2 { tag: '1', item: '2' }
  app/shop/[...slug]/page.js /shop/1/2 { slug: ['1', '2'] }
- searchParams - 包含当前 URL 的搜索参数的对象。示例：
  
  URL searchParams
  /shop?a=1 { a: '1' }
  /shop?a=1&b=2 { a: '1', b: '2' }
  /shop?a=1&a=2 { a: ['1', '2'] }
parent - 父路由段解析元数据的 Promise。

路由	URL	`params`
`app/shop/[slug]/page.js`	`/shop/1`	`{ slug: '1' }`
`app/shop/[tag]/[item]/page.js`	`/shop/1/2`	`{ tag: '1', item: '2' }`
`app/shop/[...slug]/page.js`	`/shop/1/2`	`{ slug: ['1', '2'] }`

URL	`searchParams`
`/shop?a=1`	`{ a: '1' }`
`/shop?a=1&b=2`	`{ a: '1', b: '2' }`
`/shop?a=1&a=2`	`{ a: ['1', '2'] }`

返回值

generateMetadata 应该返回一个包含一个或多个元数据字段的 Metadata 对象。

提示：

如果元数据不依赖于运行时信息，应该使用静态 metadata 对象而不是 generateMetadata 来定义。

fetch 请求会自动在 generateMetadata、generateStaticParams、布局、页面和服务端组件之间进行记忆化。如果 fetch 不可用，可以使用 React cache。

searchParams 仅在 page.js 段中可用。

Next.js 的 redirect() 和 notFound() 方法也可以在 generateMetadata 内使用。

元数据字段

支持以下字段：

`title`

title 属性用于设置文档的标题。它可以定义为简单的字符串或可选的模板对象。

String

layout.js | page.js
export const metadata = {
  title: 'Next.js',
}

<head> output
<title>Next.js</title>

`default`

title.default 可用于为不定义 title 的子路由段提供后备标题。

app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    default: 'Acme',
  },
}

app/about/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {}

// Output: <title>Acme</title>

`template`

title.template 可用于为子路由段中定义的 titles 添加前缀或后缀。

TypeScript
JavaScript

app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
    default: 'Acme', // 创建模板时需要默认值
  },
}

app/layout.js
export const metadata = {
  title: {
    template: '%s | Acme',
    default: 'Acme', // 创建模板时需要默认值
  },
}

```tsx filename="app/about/page.tsx" switcher
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'About',
}

// Output: <title>About | Acme</title>

JavaScript

app/about/page.js
export const metadata = {
  title: 'About',
}

// Output: <title>About | Acme</title>

提示：

title.template 适用于子路由段，而不是定义它的段。这意味着：

当你添加 title.template 时，title.default 是必需的。

在 layout.js 中定义的 title.template 不会应用于同一路由段的 page.js 中定义的 title。

在 page.js 中定义的 title.template 没有效果，因为页面始终是终止段（它没有任何子路由段）。

如果路由没有定义 title 或 title.default，title.template 没有效果。

`absolute`

title.absolute 可用于提供忽略父段中设置的 title.template 的标题。

TypeScript
JavaScript

app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
  },
}

app/layout.js
export const metadata = {
  title: {
    template: '%s | Acme',
  },
}

TypeScript
JavaScript

app/about/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    absolute: 'About',
  },
}

// Output: <title>About</title>

app/about/page.js
export const metadata = {
  title: {
    absolute: 'About',
  },
}

// Output: <title>About</title>

提示：

layout.js

title（字符串）和 title.default 为子段（不定义自己的 title）定义默认标题。如果存在，它将增强最近父段的 title.template。

title.absolute 为子段定义默认标题。它忽略父段的 title.template。

title.template 为子段定义新的标题模板。

page.js

如果页面没有定义自己的标题，将使用最近父级的解析标题。

title（字符串）定义路由标题。如果存在，它将增强最近父段的 title.template。

title.absolute 定义路由标题。它忽略父段的 title.template。

title.template 在 page.js 中没有效果，因为页面始终是路由的终止段。

`description`

layout.js | page.js
export const metadata = {
  description: 'The React Framework for the Web',
}

<head> output
<meta name="description" content="The React Framework for the Web" />

其他字段

layout.js | page.js
export const metadata = {
  generator: 'Next.js',
  applicationName: 'Next.js',
  referrer: 'origin-when-cross-origin',
  keywords: ['Next.js', 'React', 'JavaScript'],
  authors: [{ name: 'Seb' }, { name: 'Josh', url: 'https://nextjs.org' }],
  creator: 'Jiachi Liu',
  publisher: 'Sebastian Markbåge',
  formatDetection: {
    email: false,
    address: false,
    telephone: false,
  },
}

<head> output
<meta name="application-name" content="Next.js" />
<meta name="author" content="Seb" />
<link rel="author" href="https://nextjs.org" />
<meta name="author" content="Josh" />
<meta name="generator" content="Next.js" />
<meta name="keywords" content="Next.js,React,JavaScript" />
<meta name="referrer" content="origin-when-cross-origin" />
<meta name="color-scheme" content="dark" />
<meta name="creator" content="Jiachi Liu" />
<meta name="publisher" content="Sebastian Markbåge" />
<meta name="format-detection" content="telephone=no, address=no, email=no" />

`metadataBase`

metadataBase 是一个便利选项，用于为需要完全限定 URL 的 metadata 字段设置基础 URL 前缀。

metadataBase 允许在当前路由段及以下定义的基于 URL 的 metadata 字段使用相对路径而不是其他必需的绝对 URL。
字段的相对路径将与 metadataBase 组合以形成完全限定的 URL。

layout.js | page.js
export const metadata = {
  metadataBase: new URL('https://acme.com'),
  alternates: {
    canonical: '/',
    languages: {
      'en-US': '/en-US',
      'de-DE': '/de-DE',
    },
  },
  openGraph: {
    images: '/og-image.png',
  },
}

<head> output
<link rel="canonical" href="https://acme.com" />
<link rel="alternate" hreflang="en-US" href="https://acme.com/en-US" />
<link rel="alternate" hreflang="de-DE" href="https://acme.com/de-DE" />
<meta property="og:image" content="https://acme.com/og-image.png" />

提示：

metadataBase 通常在根 app/layout.js 中设置，以应用于所有路由的基于 URL 的 metadata 字段。

所有需要绝对 URL 的基于 URL 的 metadata 字段都可以使用 metadataBase 选项进行配置。

metadataBase 可以包含子域，例如 https://app.acme.com 或基础路径，例如 https://acme.com/start/from/here

如果 metadata 字段提供绝对 URL，metadataBase 将被忽略。

在没有配置 metadataBase 的情况下在基于 URL 的 metadata 字段中使用相对路径将导致构建错误。

Next.js 将规范化 metadataBase（例如 https://acme.com/）和相对字段（例如 /path）之间的重复斜杠为单个斜杠（例如 https://acme.com/path）

URL 组合

URL 组合优先考虑开发者意图而不是默认的目录遍历语义。

metadataBase 和 metadata 字段之间的尾随斜杠被规范化。
metadata 字段中的"绝对"路径（通常会替换整个 URL 路径）被视为"相对"路径（从 metadataBase 的末尾开始）。

例如，给定以下 metadataBase：

TypeScript
JavaScript

app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  metadataBase: new URL('https://acme.com'),
}

app/layout.js
export const metadata = {
  metadataBase: new URL('https://acme.com'),
}

继承上述 metadataBase 并设置自己值的任何 metadata 字段将按如下方式解析：

`metadata` 字段	解析的 URL
`/`	`https://acme.com`
`./`	`https://acme.com`
`payments`	`https://acme.com/payments`
`/payments`	`https://acme.com/payments`
`./payments`	`https://acme.com/payments`
`../payments`	`https://acme.com/payments`
`https://beta.acme.com/payments`	`https://beta.acme.com/payments`

`openGraph`

layout.js | page.js
export const metadata = {
  openGraph: {
    title: 'Next.js',
    description: 'The React Framework for the Web',
    url: 'https://nextjs.org',
    siteName: 'Next.js',
    images: [
      {
        url: 'https://nextjs.org/og.png', // 必须是绝对 URL
        width: 800,
        height: 600,
      },
      {
        url: 'https://nextjs.org/og-alt.png', // 必须是绝对 URL
        width: 1800,
        height: 1600,
        alt: 'My custom alt',
      },
    ],
    videos: [
      {
        url: 'https://nextjs.org/video.mp4', // 必须是绝对 URL
        width: 800,
        height: 600,
      },
    ],
    audio: [
      {
        url: 'https://nextjs.org/audio.mp3', // 必须是绝对 URL
      },
    ],
    locale: 'en_US',
    type: 'website',
  },
}

<head> output
<meta property="og:title" content="Next.js" />
<meta property="og:description" content="The React Framework for the Web" />
<meta property="og:url" content="https://nextjs.org/" />
<meta property="og:site_name" content="Next.js" />
<meta property="og:locale" content="en_US" />
<meta property="og:image" content="https://nextjs.org/og.png" />
<meta property="og:image:width" content="800" />
<meta property="og:image:height" content="600" />
<meta property="og:image" content="https://nextjs.org/og-alt.png" />
<meta property="og:image:width" content="1800" />
<meta property="og:image:height" content="1600" />
<meta property="og:image:alt" content="My custom alt" />
<meta property="og:video" content="https://nextjs.org/video.mp4" />
<meta property="og:video:width" content="800" />
<meta property="og:video:height" content="600" />
<meta property="og:audio" content="https://nextjs.org/audio.mp3" />
<meta property="og:type" content="website" />

layout.js | page.js
export const metadata = {
  openGraph: {
    title: 'Next.js',
    description: 'The React Framework for the Web',
    type: 'article',
    publishedTime: '2023-01-01T00:00:00.000Z',
    authors: ['Seb', 'Josh'],
  },
}

<head> output
<meta property="og:title" content="Next.js" />
<meta property="og:description" content="The React Framework for the Web" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2023-01-01T00:00:00.000Z" />
<meta property="article:author" content="Seb" />
<meta property="article:author" content="Josh" />

提示：

对于 Open Graph 图像，使用基于文件的元数据 API 可能更方便。基于文件的 API 将自动为你生成正确的元数据，而不必同步配置导出与实际文件。

`robots`

layout.tsx | page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  robots: {
    index: true,
    follow: true,
    nocache: false,
    googleBot: {
      index: true,
      follow: true,
      noimageindex: false,
      'max-video-preview': -1,
      'max-image-preview': 'large',
      'max-snippet': -1,
    },
  },
}

<head> output
<meta name="robots" content="index, follow" />
<meta
  name="googlebot"
  content="index, follow, max-video-preview:-1, max-image-preview:large, max-snippet:-1"
/>

`icons`

提示：我们建议尽可能使用基于文件的元数据 API 来处理图标。基于文件的 API 将自动为你生成正确的元数据，而不必同步配置导出与实际文件。

layout.js | page.js
export const metadata = {
  icons: {
    icon: '/icon.png',
    shortcut: '/shortcut-icon.png',
    apple: '/apple-icon.png',
    other: {
      rel: 'apple-touch-icon-precomposed',
      url: '/apple-touch-icon-precomposed.png',
    },
  },
}

<head> output
<link rel="shortcut icon" href="/shortcut-icon.png" />
<link rel="icon" href="/icon.png" />
<link rel="apple-touch-icon" href="/apple-icon.png" />
<link
  rel="apple-touch-icon-precomposed"
  href="/apple-touch-icon-precomposed.png"
/>

layout.js | page.js
export const metadata = {
  icons: {
    icon: [
      { url: '/icon.png' },
      new URL('/icon.png', 'https://example.com'),
      { url: '/icon-dark.png', media: '(prefers-color-scheme: dark)' },
    ],
    shortcut: ['/shortcut-icon.png'],
    apple: [
      { url: '/apple-icon.png' },
      { url: '/apple-icon-x3.png', sizes: '180x180', type: 'image/png' },
    ],
    other: [
      {
        rel: 'apple-touch-icon-precomposed',
        url: '/apple-touch-icon-precomposed.png',
      },
    ],
  },
}

<head> output
<link rel="shortcut icon" href="/shortcut-icon.png" />
<link rel="icon" href="/icon.png" />
<link rel="icon" href="https://example.com/icon.png" />
<link rel="icon" href="/icon-dark.png" media="(prefers-color-scheme: dark)" />
<link rel="apple-touch-icon" href="/apple-icon.png" />
<link
  rel="apple-touch-icon-precomposed"
  href="/apple-touch-icon-precomposed.png"
/>
<link
  rel="apple-touch-icon"
  href="/apple-icon-x3.png"
  sizes="180x180"
  type="image/png"
/>

提示：msapplication-* meta 标签在 Microsoft Edge 的 Chromium 版本中不再受支持，因此不再需要。

`themeColor`

已弃用：metadata 中的 themeColor 选项在 Next.js 14 中已弃用。请改用 viewport 配置。

`colorScheme`

已弃用：metadata 中的 colorScheme 选项在 Next.js 14 中已弃用。请改用 viewport 配置。

`manifest`

Web 应用程序清单，如 Web 应用程序清单规范中所定义。

layout.js | page.js
export const metadata = {
  manifest: 'https://nextjs.org/manifest.json',
}

<head> output
<link rel="manifest" href="https://nextjs.org/manifest.json" />

`twitter`

Twitter 规范（令人惊讶地）不仅用于 X（前身为 Twitter）。

了解更多关于 Twitter Card 标记参考。

layout.js | page.js
export const metadata = {
  twitter: {
    card: 'summary_large_image',
    title: 'Next.js',
    description: 'The React Framework for the Web',
    siteId: '1467726470533754880',
    creator: '@nextjs',
    creatorId: '1467726470533754880',
    images: ['https://nextjs.org/og.png'], // Must be an absolute URL
  },
}

<head> output
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site:id" content="1467726470533754880" />
<meta name="twitter:creator" content="@nextjs" />
<meta name="twitter:creator:id" content="1467726470533754880" />
<meta name="twitter:title" content="Next.js" />
<meta name="twitter:description" content="The React Framework for the Web" />
<meta name="twitter:image" content="https://nextjs.org/og.png" />

layout.js | page.js
export const metadata = {
  twitter: {
    card: 'app',
    title: 'Next.js',
    description: 'The React Framework for the Web',
    siteId: '1467726470533754880',
    creator: '@nextjs',
    creatorId: '1467726470533754880',
    images: {
      url: 'https://nextjs.org/og.png',
      alt: 'Next.js Logo',
    },
    app: {
      name: 'twitter_app',
      id: {
        iphone: 'twitter_app://iphone',
        ipad: 'twitter_app://ipad',
        googleplay: 'twitter_app://googleplay',
      },
      url: {
        iphone: 'https://iphone_url',
        ipad: 'https://ipad_url',
      },
    },
  },
}

<head> output
<meta name="twitter:site:id" content="1467726470533754880" />
<meta name="twitter:creator" content="@nextjs" />
<meta name="twitter:creator:id" content="1467726470533754880" />
<meta name="twitter:title" content="Next.js" />
<meta name="twitter:description" content="The React Framework for the Web" />
<meta name="twitter:card" content="app" />
<meta name="twitter:image" content="https://nextjs.org/og.png" />
<meta name="twitter:image:alt" content="Next.js Logo" />
<meta name="twitter:app:name:iphone" content="twitter_app" />
<meta name="twitter:app:id:iphone" content="twitter_app://iphone" />
<meta name="twitter:app:id:ipad" content="twitter_app://ipad" />
<meta name="twitter:app:id:googleplay" content="twitter_app://googleplay" />
<meta name="twitter:app:url:iphone" content="https://iphone_url" />
<meta name="twitter:app:url:ipad" content="https://ipad_url" />
<meta name="twitter:app:name:ipad" content="twitter_app" />
<meta name="twitter:app:name:googleplay" content="twitter_app" />

`viewport`

已弃用：metadata 中的 viewport 选项在 Next.js 14 中已弃用。请改用 viewport 配置。

`verification`

layout.js | page.js
export const metadata = {
  verification: {
    google: 'google',
    yandex: 'yandex',
    yahoo: 'yahoo',
    other: {
      me: ['my-email', 'my-link'],
    },
  },
}

<head> output
<meta name="google-site-verification" content="google" />
<meta name="y_key" content="yahoo" />
<meta name="yandex-verification" content="yandex" />
<meta name="me" content="my-email" />
<meta name="me" content="my-link" />

`appleWebApp`

layout.js | page.js
export const metadata = {
  itunes: {
    appId: 'myAppStoreID',
    appArgument: 'myAppArgument',
  },
  appleWebApp: {
    title: 'Apple Web App',
    statusBarStyle: 'black-translucent',
    startupImage: [
      '/assets/startup/apple-touch-startup-image-768x1004.png',
      {
        url: '/assets/startup/apple-touch-startup-image-1536x2008.png',
        media: '(device-width: 768px) and (device-height: 1024px)',
      },
    ],
  },
}

<head> output
<meta
  name="apple-itunes-app"
  content="app-id=myAppStoreID, app-argument=myAppArgument"
/>
<meta name="mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-title" content="Apple Web App" />
<link
  href="/assets/startup/apple-touch-startup-image-768x1004.png"
  rel="apple-touch-startup-image"
/>
<link
  href="/assets/startup/apple-touch-startup-image-1536x2008.png"
  media="(device-width: 768px) and (device-height: 1024px)"
  rel="apple-touch-startup-image"
/>
<meta
  name="apple-mobile-web-app-status-bar-style"
  content="black-translucent"
/>

`alternates`

layout.js | page.js
export const metadata = {
  alternates: {
    canonical: 'https://nextjs.org',
    languages: {
      'en-US': 'https://nextjs.org/en-US',
      'de-DE': 'https://nextjs.org/de-DE',
    },
    media: {
      'only screen and (max-width: 600px)': 'https://nextjs.org/mobile',
    },
    types: {
      'application/rss+xml': 'https://nextjs.org/rss',
    },
  },
}

<head> output
<link rel="canonical" href="https://nextjs.org" />
<link rel="alternate" hreflang="en-US" href="https://nextjs.org/en-US" />
<link rel="alternate" hreflang="de-DE" href="https://nextjs.org/de-DE" />
<link
  rel="alternate"
  media="only screen and (max-width: 600px)"
  href="https://nextjs.org/mobile"
/>
<link
  rel="alternate"
  type="application/rss+xml"
  href="https://nextjs.org/rss"
/>

`appLinks`

layout.js | page.js
export const metadata = {
  appLinks: {
    ios: {
      url: 'https://nextjs.org/ios',
      app_store_id: 'app_store_id',
    },
    android: {
      package: 'com.example.android/package',
      app_name: 'app_name_android',
    },
    web: {
      url: 'https://nextjs.org/web',
      should_fallback: true,
    },
  },
}

<head> output
<meta property="al:ios:url" content="https://nextjs.org/ios" />
<meta property="al:ios:app_store_id" content="app_store_id" />
<meta property="al:android:package" content="com.example.android/package" />
<meta property="al:android:app_name" content="app_name_android" />
<meta property="al:web:url" content="https://nextjs.org/web" />
<meta property="al:web:should_fallback" content="true" />

`archives`

描述具有历史价值的记录、文档或其他材料的集合（来源）。

layout.js | page.js
export const metadata = {
  archives: ['https://nextjs.org/13'],
}

<head> output
<link rel="archives" href="https://nextjs.org/13" />

`assets`

layout.js | page.js
export const metadata = {
  assets: ['https://nextjs.org/assets'],
}

<head> output
<link rel="assets" href="https://nextjs.org/assets" />

`bookmarks`

layout.js | page.js
export const metadata = {
  bookmarks: ['https://nextjs.org/13'],
}

<head> output
<link rel="bookmarks" href="https://nextjs.org/13" />

`category`

layout.js | page.js
export const metadata = {
  category: 'technology',
}

<head> output
<meta name="category" content="technology" />

`facebook`

你可以将 Facebook 应用或 Facebook 账户连接到你的网页以使用某些 Facebook 社交插件 Facebook 文档

提示：你可以指定 appId 或 admins，但不能同时指定两者。

layout.js | page.js
export const metadata = {
  facebook: {
    appId: '12345678',
  },
}

<head> output
<meta property="fb:app_id" content="12345678" />

layout.js | page.js
export const metadata = {
  facebook: {
    admins: '12345678',
  },
}

<head> output
<meta property="fb:admins" content="12345678" />

如果你想生成多个 fb:admins meta 标签，可以使用数组值。

layout.js | page.js
export const metadata = {
  facebook: {
    admins: ['12345678', '87654321'],
  },
}

<head> output
<meta property="fb:admins" content="12345678" />
<meta property="fb:admins" content="87654321" />

`pinterest`

你可以在网页上启用或禁用 Pinterest Rich Pins。

layout.js | page.js
export const metadata = {
  pinterest: {
    richPin: true,
  },
}

<head> output
<meta name="pinterest-rich-pin" content="true" />

`other`

所有元数据选项都应该使用内置支持来覆盖。但是，可能有特定于你网站的自定义元数据标签，或者刚刚发布的全新元数据标签。你可以使用 other 选项来渲染任何自定义元数据标签。

layout.js | page.js
export const metadata = {
  other: {
    custom: 'meta',
  },
}

<head> output
<meta name="custom" content="meta" />

如果你想生成多个相同键的 meta 标签，可以使用数组值。

layout.js | page.js
export const metadata = {
  other: {
    custom: ['meta1', 'meta2'],
  },
}

<head> output
<meta name="custom" content="meta1" /> <meta name="custom" content="meta2" />

类型

你可以通过使用 Metadata 类型为元数据添加类型安全性。如果你在 IDE 中使用内置 TypeScript 插件，你不需要手动添加类型，但你仍然可以显式添加它。

`metadata` object

layout.tsx | page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Next.js',
}

`generateMetadata` function

Regular function

layout.tsx | page.tsx
import type { Metadata } from 'next'

export function generateMetadata(): Metadata {
  return {
    title: 'Next.js',
  }
}

Async function

layout.tsx | page.tsx
import type { Metadata } from 'next'

export async function generateMetadata(): Promise<Metadata> {
  return {
    title: 'Next.js',
  }
}

With segment props

layout.tsx | page.tsx
import type { Metadata } from 'next'

type Props = {
  params: Promise<{ id: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}

export function generateMetadata({ params, searchParams }: Props): Metadata {
  return {
    title: 'Next.js',
  }
}

export default function Page({ params, searchParams }: Props) {}

With parent metadata

layout.tsx | page.tsx
import type { Metadata, ResolvingMetadata } from 'next'

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  return {
    title: 'Next.js',
  }
}

JavaScript 项目

对于 JavaScript 项目，你可以使用 JSDoc 来添加类型安全性。

layout.js | page.js
/** @type {import("next").Metadata} */
export const metadata = {
  title: 'Next.js',
}

不支持的元数据

以下元数据类型目前没有内置支持。但是，它们仍然可以在布局或页面本身中渲染。

元数据	建议
`<meta http-equiv="...">`	通过 `redirect()`、中间件、安全头使用适当的 HTTP 头
`<base>`	在布局或页面本身中渲染标签。
`<noscript>`	在布局或页面本身中渲染标签。
`<style>`	了解更多关于 Next.js 中的样式。
`<script>`	了解更多关于使用脚本。
`<link rel="stylesheet" />`	在布局或页面本身中直接 `import` 样式表。
`<link rel="preload />`	使用 ReactDOM preload 方法
`<link rel="preconnect" />`	使用 ReactDOM preconnect 方法
`<link rel="dns-prefetch" />`	使用 ReactDOM prefetchDNS 方法

资源提示

<link> 元素有许多 rel 关键字，可用于向浏览器提示可能需要外部资源。浏览器使用此信息根据关键字应用预加载优化。

虽然元数据 API 不直接支持这些提示，但你可以使用新的 ReactDOM 方法将它们安全地插入到文档的 <head> 中。

TypeScript
JavaScript

app/preload-resources.tsx
'use client'

import ReactDOM from 'react-dom'

export function PreloadResources() {
  ReactDOM.preload('...', { as: '...' })
  ReactDOM.preconnect('...', { crossOrigin: '...' })
  ReactDOM.prefetchDNS('...')

  return '...'
}

app/preload-resources.js
'use client'

import ReactDOM from 'react-dom'

export function PreloadResources() {
  ReactDOM.preload('...', { as: '...' })
  ReactDOM.preconnect('...', { crossOrigin: '...' })
  ReactDOM.prefetchDNS('...')

  return '...'
}

`<link rel="preload">`

在页面渲染（浏览器）生命周期的早期开始加载资源。MDN 文档。

ReactDOM.preload(href: string, options: { as: string })

<head> output
<link rel="preload" href="..." as="..." />

`<link rel="preconnect">`

抢先启动到源的连接。MDN 文档。

ReactDOM.preconnect(href: string, options?: { crossOrigin?: string })

<head> output
<link rel="preconnect" href="..." crossorigin />

`<link rel="dns-prefetch">`

在请求资源之前尝试解析域名。MDN 文档。

ReactDOM.prefetchDNS(href: string)

<head> output
<link rel="dns-prefetch" href="..." />

提示：

这些方法目前仅在客户端组件中受支持，这些组件在初始页面加载时仍然是服务端渲染的。

Next.js 内置功能如 next/font、next/image 和 next/script 自动处理相关的资源提示。

行为

默认字段

有两个默认的 meta 标签总是被添加，即使路由没有定义元数据：

meta charset 标签设置网站字符编码。
meta viewport 标签设置网站的视口宽度和缩放比例以适应不同设备。

<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />

提示：你可以覆盖默认的 viewport meta 标签。

流式元数据

generateMetadata 返回的元数据被流式传输到客户端。这允许 Next.js 在元数据解析后立即将其注入到 HTML 中。

流式元数据被附加到 <body> 标签。由于元数据主要针对机器人和爬虫，Next.js 为可以执行 JavaScript 并检查完整 DOM 的机器人（例如 Googlebot）流式传输元数据。我们已经验证这些机器人正确解释元数据。

对于HTML 受限的无法运行 JavaScript 的机器人（例如 Twitterbot），元数据会继续阻止页面渲染，并放置在 <head> 标签中。

Next.js 自动检测传入请求的用户代理，以确定是提供流式元数据还是回退到阻塞元数据。

如果你需要自定义此列表，可以使用 next.config.js 中的 htmlLimitedBots 选项手动定义它们。Next.js 将确保匹配此正则表达式的用户代理在请求你的网页时接收阻塞元数据。

TypeScript
JavaScript

next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}

export default config

next.config.js
module.exports = {
  htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}

指定 htmlLimitedBots 配置将覆盖 Next.js 的默认列表，允许你完全控制哪些用户代理应该选择此行为。

覆盖 htmlLimitedBots 可能导致更长的响应时间。流式元数据是一个高级功能，默认设置应该对大多数情况足够。

排序

元数据按顺序评估，从根段开始到最接近最终 page.js 段的段。例如：

app/layout.tsx（根布局）
app/blog/layout.tsx（嵌套博客布局）
app/blog/[slug]/page.tsx（博客页面）

合并

按照评估顺序，从同一路由的多个段导出的元数据对象被浅层合并在一起，形成路由的最终元数据输出。重复的键根据它们的顺序被替换。

这意味着在较早段中定义的具有嵌套字段（如 openGraph 和 robots）的元数据被定义它们的最后一个段覆盖。

覆盖字段

app/layout.js
export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}

app/blog/page.js
export const metadata = {
  title: 'Blog',
  openGraph: {
    title: 'Blog',
  },
}

// 输出：
// <title>Blog</title>
// <meta property="og:title" content="Blog" />

在上面的示例中：

app/layout.js 中的 title 被 app/blog/page.js 中的 title 替换。
app/layout.js 中的所有 openGraph 字段在 app/blog/page.js 中被替换，因为 app/blog/page.js 设置了 openGraph 元数据。注意缺少 openGraph.description。

如果你想在段之间共享一些嵌套字段同时覆盖其他字段，可以将它们提取到单独的变量中：

app/shared-metadata.js
export const openGraphImage = { images: ['http://...'] }

app/page.js
import { openGraphImage } from './shared-metadata'

export const metadata = {
  openGraph: {
    ...openGraphImage,
    title: 'Home',
  },
}

app/about/page.js
import { openGraphImage } from '../shared-metadata'

export const metadata = {
  openGraph: {
    ...openGraphImage,
    title: 'About',
  },
}

在上面的示例中，OG 图像在 app/layout.js 和 app/about/page.js 之间共享，而标题不同。

继承字段

app/layout.js
export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}

app/about/page.js
export const metadata = {
  title: 'About',
}

// 输出：
// <title>About</title>
// <meta property="og:title" content="Acme" />
// <meta property="og:description" content="Acme is a..." />

说明

app/layout.js 中的 title 被 app/about/page.js 中的 title 替换。
app/layout.js 中的所有 openGraph 字段在 app/about/page.js 中被继承，因为 app/about/page.js 没有设置 openGraph 元数据。

版本历史

版本	更改
`v15.2.0`	为 `generateMetadata` 引入流式支持。
`v13.2.0`	`viewport`、`themeColor` 和 `colorScheme` 已弃用，改用 `viewport` 配置。
`v13.2.0`	引入 `metadata` 和 `generateMetadata`。

metadata 对象​

generateMetadata 函数​

参考​

参数​

返回值​

元数据字段​

title​

String​

default​

template​

absolute​

description​

其他字段​

metadataBase​

URL 组合​

openGraph​

robots​

icons​

themeColor​

colorScheme​

manifest​

twitter​

viewport​

verification​

appleWebApp​

alternates​

appLinks​

archives​

assets​

bookmarks​

category​

facebook​

pinterest​

other​

类型​

metadata object​

generateMetadata function​

Regular function​

Async function​

With segment props​

With parent metadata​

JavaScript 项目​

不支持的元数据​

资源提示​

<link rel="preload">​

<link rel="preconnect">​

<link rel="dns-prefetch">​

行为​

默认字段​

流式元数据​

排序​

合并​

覆盖字段​

继承字段​

版本历史​