Menu

generateMetadata

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

metadata 对象

要定义静态 metadata，可以从 layout.js 或 page.js 文件中导出一个 Metadata 对象。

layout.tsx
TypeScript
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: '...',
  description: '...',
}
 
export default function Page() {}

查看 Metadata 字段以获取支持选项的完整列表。

generateMetadata 函数

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

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

否则，从 generateMetadata 解析的 metadata 可以在发送初始 UI 后进行流式传输。

app/products/[id]/page.tsx
TypeScript
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())
 
  // 可选地访问并扩展（而不是替换）父级 metadata
  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) {}

要获取 params 和 searchParams 的类型补全，你可以使用 PageProps<'/route'> 或 LayoutProps<'/route'> 为页面和布局分别定义第一个参数的类型。

值得注意的是：

  • Metadata 可以添加到 layout.js 和 page.js 文件中。
  • Next.js 会自动解析 metadata，并为页面创建相关的 <head> 标签。
  • metadata 对象和 generateMetadata 函数导出仅在 Server Components 中支持。
  • 你不能在同一个路由段中同时导出 metadata 对象和 generateMetadata 函数。
  • generateMetadata 中的 fetch 请求会自动为 generateMetadata、generateStaticParams、Layouts、Pages 和 Server Components 中的相同数据进行记忆化。
  • 如果 fetch 不可用，可以使用 React cache。
  • 基于文件的 metadata 具有更高的优先级，将覆盖 metadata 对象和 generateMetadata 函数。

参考

参数

generateMetadata 函数接受以下参数：

  • props - 一个包含当前路由参数的对象：

    • params - 一个包含从根段到调用 generateMetadata 的段的动态路由参数对象。示例：

      路由URLparams
      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 的搜索参数的对象。示例：

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

  • parent - 来自父路由段的已解析 metadata 的 promise。

返回值

generateMetadata 应返回一个包含一个或多个 metadata 字段的 Metadata 对象。

值得注意的是：

  • 如果 metadata 不依赖于运行时信息，应使用静态 metadata 对象而不是 generateMetadata。
  • fetch 请求会自动为 generateMetadata、generateStaticParams、Layouts、Pages 和 Server Components 中的相同数据进行记忆化。如果 fetch 不可用，可以使用 React cache。
  • searchParams 仅在 page.js 段中可用。
  • Next.js 的 redirect() 和 notFound() 方法也可以在 generateMetadata 中使用。

Metadata 字段

支持以下字段：

title

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

String
layout.js
export const metadata = {
  title: 'Next.js',
}
<head>
<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 = {}
 
// 输出：<title>Acme</title>
template

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

app/layout.tsx
TypeScript
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
    default: 'Acme', // 创建模板时需要默认值
  },
}
app/about/page.tsx
TypeScript
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'About',
}
 
// 输出：<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 的标题。

app/layout.tsx
TypeScript
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
  },
}
app/about/page.tsx
TypeScript
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: {
    absolute: 'About',
  },
}
 
// 输出：<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
export const metadata = {
  description: 'The React Framework for the Web',
}
<head>
<meta name="description" content="The React Framework for the Web" />

其他字段

layout.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>
<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
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>
<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：

app/layout.tsx
TypeScript
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  metadataBase: new URL('https://acme.com'),
}

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

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

openGraph

layout.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>
<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
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>
<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 图片，使用基于文件的 Metadata API 可能更方便。基于文件的 API 会自动为你生成正确的 metadata，而不必将配置导出与实际文件同步。

robots

layout.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>
<meta name="robots" content="index, follow" />
<meta
  name="googlebot"
  content="index, follow, max-video-preview:-1, max-image-preview:large, max-snippet:-1"
/>

icons

值得注意的是：我们建议尽可能使用基于文件的 Metadata API 来处理图标。基于文件的 API 会自动为你生成正确的 metadata，而不必将配置导出与实际文件同步。

layout.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>
<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
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>
<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"
/>

值得注意的是：Microsoft Edge 的 Chromium 构建版本不再支持 msapplication-* meta 标签，因此不再需要。

themeColor

已弃用：从 Next.js 14 开始，metadata 中的 themeColor 选项已弃用。请使用 viewport 配置代替。

colorScheme

已弃用：从 Next.js 14 开始，metadata 中的 colorScheme 选项已弃用。请使用 viewport 配置代替。

manifest

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

layout.js
export const metadata = {
  manifest: 'https://nextjs.org/manifest.json',
}
<head>
<link rel="manifest" href="https://nextjs.org/manifest.json" />

twitter

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

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

layout.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'], // 必须是绝对 URL
  },
}
<head>
<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
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>
<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

已弃用：从 Next.js 14 开始，metadata 中的 viewport 选项已弃用。请使用 viewport 配置代替。

verification

layout.js
export const metadata = {
  verification: {
    google: 'google',
    yandex: 'yandex',
    yahoo: 'yahoo',
    other: {
      me: ['my-email', 'my-link'],
    },
  },
}
<head>
<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
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>
<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
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>
<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
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>
<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
export const metadata = {
  archives: ['https://nextjs.org/13'],
}
<head>
<link rel="archives" href="https://nextjs.org/13" />

assets

layout.js
export const metadata = {
  assets: ['https://nextjs.org/assets'],
}
<head>
<link rel="assets" href="https://nextjs.org/assets" />

bookmarks

layout.js
export const metadata = {
  bookmarks: ['https://nextjs.org/13'],
}
<head>
<link rel="bookmarks" href="https://nextjs.org/13" />

category

layout.js
export const metadata = {
  category: 'technology',
}
<head>
<meta name="category" content="technology" />

facebook

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

值得注意的是：你可以指定 appId 或 admins，但不能同时指定两者。

layout.js
export const metadata = {
  facebook: {
    appId: '12345678',
  },
}
<head>
<meta property="fb:app_id" content="12345678" />
layout.js
export const metadata = {
  facebook: {
    admins: '12345678',
  },
}
<head>
<meta property="fb:admins" content="12345678" />

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

layout.js
export const metadata = {
  facebook: {
    admins: ['12345678', '87654321'],
  },
}
<head>
<meta property="fb:admins" content="12345678" />
<meta property="fb:admins" content="87654321" />

pinterest

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

layout.js
export const metadata = {
  pinterest: {
    richPin: true,
  },
}
<head>
<meta name="pinterest-rich-pin" content="true" />

other

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

layout.js
export const metadata = {
  other: {
    custom: 'meta',
  },
}
<head>
<meta name="custom" content="meta" />

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

layout.js
export const metadata = {
  other: {
    custom: ['meta1', 'meta2'],
  },
}
<head>
<meta name="custom" content="meta1" /> <meta name="custom" content="meta2" />

类型

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

metadata 对象

layout.tsx
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'Next.js',
}

generateMetadata 函数

常规函数
layout.tsx
import type { Metadata } from 'next'
 
export function generateMetadata(): Metadata {
  return {
    title: 'Next.js',
  }
}
异步函数
layout.tsx
import type { Metadata } from 'next'
 
export async function generateMetadata(): Promise<Metadata> {
  return {
    title: 'Next.js',
  }
}
带有段 props
layout.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) {}
带有父 metadata
layout.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
/** @type {import("next").Metadata} */
export const metadata = {
  title: 'Next.js',
}

不支持的 Metadata

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

Metadata建议
<meta http-equiv="...">通过 redirect()、Proxy、Security Headers 使用适当的 HTTP Headers
<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 关键字，可用于向浏览器提示可能需要外部资源。浏览器使用此信息根据关键字应用预加载优化。

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

app/preload-resources.tsx
TypeScript
'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>
<link rel="preload" href="..." as="..." />
<link rel="preconnect">

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

ReactDOM.preconnect(href: string, options?: { crossOrigin?: string })
<head>
<link rel="preconnect" href="..." crossorigin />

<link rel="dns-prefetch">

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

ReactDOM.prefetchDNS(href: string)
<head>
<link rel="dns-prefetch" href="..." />

值得注意的是：

  • 这些方法目前仅在 Client Components 中支持，在初始页面加载时仍然是服务器端渲染的。
  • Next.js 的内置功能，如 next/font、next/image 和 next/script，会自动处理相关的资源提示。

行为

默认字段

即使路由未定义 metadata，也始终添加两个默认的 meta 标签：

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

值得注意的是：你可以覆盖默认的 viewport meta 标签。

流式传输 metadata

流式传输 metadata 允许 Next.js 渲染初始 UI 并将其发送到浏览器，而无需等待 generateMetadata 完成。

当 generateMetadata 解析时，生成的 metadata 标签会附加到 <body> 标签中。我们已经验证，执行 JavaScript 并检查完整 DOM 的机器人（例如 Googlebot）可以正确解释 metadata。

对于仅支持 HTML 的机器人（无法执行 JavaScript，例如 facebookexternalhit），metadata 会继续阻塞页面渲染。生成的 metadata 将在 <head> 标签中可用。

Next.js 通过查看 User Agent header 自动检测仅支持 HTML 的机器人。你可以在 Next.js 配置文件中使用 htmlLimitedBots 选项覆盖默认的 User Agent 列表。

要完全禁用流式传输 metadata：

next.config.ts
TypeScript
import type { NextConfig } from 'next'
 
const config: NextConfig = {
  htmlLimitedBots: /.*/,
}
 
export default config

流式传输 metadata 通过减少 TTFB 来改善感知性能，并可以帮助降低 LCP 时间。

覆盖 htmlLimitedBots 可能会导致更长的响应时间。流式传输 metadata 是一项高级功能，默认设置应该适用于大多数情况。

顺序

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

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

合并

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

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

覆盖字段

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 metadata。请注意缺少 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 metadata。

版本历史

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

Next Steps

查看所有 Metadata API 选项。

Metadata Files

API documentation for the metadata file conventions.

generateViewport

generateViewport 函数的 API 参考。