NNext.js 中文网 GitHub

generateMetadata

了解如何为 Next.js 应用程序添加元数据,以改善搜索引擎优化(SEO)和网络分享效果。

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

metadata 对象#

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

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

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

export default function Page() {}
layout.js | page.js
export const metadata = {
  title: '...',
  description: '...',
}

export default function Page() {}

有关支持选项的完整列表,请参阅 Metadata 字段。

generateMetadata 函数#

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

解析 generateMetadata 是页面渲染的一部分。如果页面可以被预渲染,且 generateMetadata 不引入动态行为,则生成的元数据会包含在页面的初始 HTML 中。

否则,从 generateMetadata 解析出的元数据可以在发送初始 UI 后进行流式传输。

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 }) {}

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

小知识:

  • 元数据可以添加到 layout.js 和 page.js 文件中。
  • Next.js 会自动解析元数据,并为页面创建相关的 <head> 标签。
  • metadata 对象和 generateMetadata 函数导出仅在 Server Components 中受支持。
  • 你不能从同一路由段同时导出 metadata 对象和 generateMetadata 函数。
  • generateMetadata 内部的 fetch 请求会在 generateMetadata、generateStaticParams、Layouts、Pages 和 Server Components 之间针对相同数据自动记忆化。
  • 如果 fetch 不可用,可以使用 React cache。
  • 页面中来自 metadata 或 generateMetadata 的显式 openGraph.images 或 twitter.images 属性会覆盖同一路由段中或从父级路由段继承的相应文件型图片。

为什么 generateMetadata 仅限 Server Component#

generateMetadata 和 metadata 导出仅在 Server Components 中受支持,因为元数据必须在页面组件渲染之前在服务端解析。这使 Next.js 能够将元数据包含在初始 HTML 响应中。

如果你需要使用 Client Component 功能,请保持 page.tsx 为 Server Component,并将 Client Component 逻辑移到单独的文件中:

app/page.tsx
import type { Metadata } from 'next'
import { InteractiveComponent } from './interactive-component'

export const metadata: Metadata = {
  title: 'My Page',
}

export default function Page() {
  return <InteractiveComponent />
}
app/page.js
import { InteractiveComponent } from './interactive-component'

export const metadata = {
  title: 'My Page',
}

export default function Page() {
  return <InteractiveComponent />
}
app/interactive-component.tsx
'use client'

export function InteractiveComponent() {
  // 客户端交互(hook、事件处理程序等)
}
app/interactive-component.js
'use client'

export function InteractiveComponent() {
  // 客户端交互(hook、事件处理程序等)
}

参考#

参数#

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 - 来自父级路由段的已解析元数据的 promise。

返回值#

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

小知识:

  • 如果元数据不依赖请求信息,应使用静态 metadata 对象而不是 generateMetadata 来定义。
  • fetch 请求会在 generateMetadata、generateStaticParams、Layouts、Pages 和 Server Components 之间针对相同数据自动记忆化。如果 fetch 不可用,可以使用 React cache。
  • searchParams 仅在 page.js 路由段中可用。
  • Next.js 的 redirect() 和 notFound() 方法也可以在 generateMetadata 中使用。

Metadata 字段#

静态 metadata 对象和 generateMetadata 返回的对象可使用相同的字段。字段是可选的,可以按需组合。

通过 viewport 或 generateViewport 配置 themeColor、colorScheme 和 viewport 设置。相应的 metadata 字段已弃用。

title#

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

字符串#

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 = {}

// 输出: <title>Acme</title>

template#

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

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', // 创建模板时必须提供默认值
  },
}
app/about/page.tsx
import type { Metadata } from 'next'

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

// 输出: <title>About | Acme</title>
app/about/page.js
export const 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
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
  },
}
app/layout.js
export const metadata = {
  title: {
    template: '%s | Acme',
  },
}
app/about/page.tsx
import type { Metadata } from 'next'

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

// 输出: <title>About</title>
app/about/page.js
export const 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 | 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',
}
<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="creator" content="Jiachi Liu" />
<meta name="publisher" content="Sebastian Markbåge" />
字段可接受的输入
applicationName、generator、creator、publisherstring
authors`{ name?: string, url?: string \
keywordsstring 或 string[];数组会用逗号连接
referrer受支持的 referrer 策略

referrer 接受 'no-referrer'、'origin'、'no-referrer-when-downgrade'、'origin-when-cross-origin'、'same-origin'、'strict-origin' 或 'strict-origin-when-cross-origin'。

metadataBase#

metadataBase 接受绝对 URL 字符串或 URL 实例。它为需要完全限定 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 字段。
  • 当 generateMetadata 使用 'use cache' 时,其返回值必须可序列化。Cache Functions 不支持 URL 实例,因此 metadataBase 等值应以字符串形式返回(例如 url.toString())。请参阅 use cache 序列化要求。
  • metadataBase 可以包含子域名,例如 https://app.acme.com,或基础路径,例如 https://acme.com/start/from/here。
  • 如果 metadata 字段提供了绝对 URL,metadataBase 将被忽略。
  • 使用相对 URL 时请显式设置 metadataBase。如果没有它,社交图片会使用回退来源(fallback origin)并可能产生警告;其他 URL 字段可以保持相对。
  • Next.js 会将 metadataBase(例如 https://acme.com/)与相对字段(例如 /path)之间重复的斜杠规范化为单个斜杠(例如 https://acme.com/path)。

URL 组合#

URL 组合更看重开发者的意图,而不是默认的目录遍历语义。

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

例如,给定以下 metadataBase:

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

formatDetection#

formatDetection 接受布尔类型的 telephone、date、address、email 和 url 字段。将字段设置为 false 会添加其 key=no 指令;true 和省略的字段不会添加指令。有关电话号码检测行为,请参阅 Apple 的 format-detection 参考。

layout.js | page.js
export const metadata = {
  formatDetection: {
    email: false,
    address: false,
    telephone: false,
  },
}
<head> output
<meta name="format-detection" content="telephone=no, address=no, email=no" />

openGraph#

openGraph 为页面配置 Open Graph 元数据。图片 URL 可以是绝对的,也可以在设置了 metadataBase 时使用相对 URL。音频和视频请使用绝对 URL。

layout.js | page.js
export const metadata = {
  openGraph: {
    title: 'Next.js',
    description: 'The React Framework for the Web',
    url: 'https://nextjs.org',
    type: 'website',
    images: [{ url: 'https://nextjs.org/og.png', width: 800, height: 600 }],
  },
}
<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:type" content="website" />
<meta property="og:image" content="https://nextjs.org/og.png" />
<meta property="og:image:width" content="800" />
<meta property="og:image:height" content="600" />

Open Graph 字段#

所有 Open Graph 类型都接受这些字段。有关属性含义和要求,请参阅 Open Graph 协议。

字段可接受的输入
titlestring 或 title 对象
description、siteName、locale、countryNamestring
urlstring 或 URL
alternateLocale、emails、phoneNumbers、faxNumbersstring 或 string[]
determiner'a'、'an'、'the'、'auto' 或 ''(省略标签)
ttlnumber
images、audio、videosURL 字符串、URL、媒体描述符,或这些值的数组

Open Graph 媒体描述符#

媒体描述符接受必需的 url 和可选的结构化属性:

字段类型适用于
url、secureUrlstring 或 URL图片、音频、视频
typestring图片、音频、视频
width、heightstring 或 number图片、视频
altstring图片

相对图片 URL 会通过 metadataBase 解析。音频和视频请使用绝对 URL。

Open Graph 类型#

设置 type 可为 Open Graph 对象类型添加字段。例如:

layout.js | page.js
export const metadata = {
  openGraph: {
    type: 'article',
    publishedTime: '2026-01-01T00:00:00.000Z',
    authors: ['https://example.com/authors/ada'],
  },
}
<head> output
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2026-01-01T00:00:00.000Z" />
<meta property="article:author" content="https://example.com/authors/ada" />

小知识:使用文件型 Metadata API从图片文件生成 Open Graph 图片元数据。

下表列出了 Next.js 为每种 type 支持的字段。所有类型还接受通用 Open Graph 字段。

type附加字段
'website'无
'article'publishedTime、modifiedTime、expirationTime、authors、section、tags
'book'isbn、releaseDate、authors、tags
'profile'firstName、lastName、username、gender
'music.song'duration、albums、musicians
'music.album'songs、musicians、releaseDate
'music.playlist'songs、creators
'music.radio_station'creators
'video.movie'actors、directors、writers、duration、releaseDate、tags
'video.episode'actors、directors、writers、duration、releaseDate、tags、series
'video.tv_show'无
'video.other'无
特定类型字段可接受的输入
publishedTime、modifiedTime、expirationTime、releaseDate日期/时间字符串
isbn、section、firstName、lastName、username、genderstring
durationnumber
tagsstring 或 string[]
authors、musicians、creators、directors、writersstring、URL,或其中任一类型的数组
seriesstring 或 URL
albums、songsstring、URL、`{ url: string \
actorsstring、URL、`{ url: string \

Next.js 会将驼峰命名的字段名映射到协议属性,例如将 modifiedTime 映射为 article:modified_time。

robots#

robots 为页面设置爬虫指令。使用 googleBot 为 Googlebot 提供单独的指令:

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

Robots 字段#

robots 和 googleBot 都接受指令字符串或对象。它们的对象字段如下所列。只有 robots 对象接受 googleBot 字段。

字段可接受的输入
index、followboolean
noarchive、nosnippet、noimageindex、nocache、notranslate、indexifembedded、nositelinkssearchboxboolean
unavailable_afterstring
'max-video-preview'number 或 string
'max-image-preview''none'、'standard' 或 'large'
'max-snippet'number
googleBotstring 或爬虫指令对象

对于 index 和 follow,false 会发出 noindex 和 nofollow。其他布尔字段仅在为 true 时发出其指令。已弃用的对象键 noindex 和 nofollow 不接受布尔选项。

有关指令含义和 Googlebot 支持情况,请参阅 Google 的 robots meta 标签参考。Next.js 会发出配置的标签;每个爬虫决定遵守哪些指令。

icons#

icons 添加图标链接,并按类别分组:

layout.js | page.js
export const metadata = {
  icons: {
    icon: [
      { url: '/icon.png' },
      { url: '/icon-dark.png', media: '(prefers-color-scheme: dark)' },
    ],
    shortcut: '/shortcut-icon.png',
    apple: '/apple-icon.png',
    other: { rel: 'mask-icon', url: '/mask-icon.svg', color: '#000000' },
  },
}
<head> output
<link rel="shortcut icon" href="/shortcut-icon.png" />
<link rel="icon" href="/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="mask-icon" href="/mask-icon.svg" color="#000000" />

小知识:使用文件型 Metadata API从图片文件生成图标元数据。

图标类别和描述符#

icons 接受 URL 字符串、URL 实例、URL/描述符数组或类别对象。每个类别接受单个项或数组;other 只接受描述符。

类别默认 rel
iconicon
shortcutshortcut icon
appleapple-touch-icon
othericon

只有描述符的 url 是必需的。显式的 rel 会覆盖类别默认值。有关属性含义,请参阅 <link> 参考。

描述符字段类型
urlstring 或 URL
type、sizes、color、rel、mediastring
fetchPriority'high'、'low' 或 'auto'

themeColor#

已弃用:metadata 中的 themeColor 选项自 Next.js 14 起已弃用。请改用 viewport 配置。

colorScheme#

已弃用:metadata 中的 colorScheme 选项自 Next.js 14 起已弃用。请改用 viewport 配置。

manifest#

manifest 链接到 web app manifest。它接受 URL 字符串或 URL 实例。

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 配置 Twitter Card 元数据。图片 URL 可以是绝对的,也可以在设置了 metadataBase 时使用相对 URL。

设置 card 以选择卡片类型。例如,使用 'summary_large_image' 可获得带有大图的卡片:

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

Twitter 字段#

所有卡片类型都接受这些字段:

字段可接受的输入
card'summary'、'summary_large_image'、'player' 或 'app'
site、siteId、creator、creatorId、descriptionstring
titlestring 或 title 对象
imagesURL 字符串、URL、图片描述符,或这些值的数组

如果省略 card,当提供的 images 解析为非空列表时,解析器会使用 'summary_large_image',否则使用 'summary'。当你需要特定卡片类型时,请显式设置 card。

当配置了 openGraph 时,其标题、描述和图片可以填充缺失的 Twitter 字段。当配置了 openGraph 或 twitter 对象时,缺失的社交标题和描述也可以继承文档的 title 和 description。

Player 卡片#

对于 card: 'player',请在 players 中提供媒体播放器 URL、流 URL 和尺寸。多个播放器请使用这些对象的数组:

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

export const metadata: Metadata = {
  twitter: {
    card: 'player',
    players: {
      playerUrl: 'https://example.com/player',
      streamUrl: 'https://example.com/video.mp4',
      width: 1280,
      height: 720,
    },
  },
}
app/layout.jsx | app/page.jsx
export const metadata = {
  twitter: {
    card: 'player',
    players: {
      playerUrl: 'https://example.com/player',
      streamUrl: 'https://example.com/video.mp4',
      width: 1280,
      height: 720,
    },
  },
}

所有四个播放器字段都是必需的。playerUrl 和 streamUrl 接受绝对 URL 字符串或 URL 实例;width 和 height 是数字。

App 卡片#

对于 card: 'app',请提供 app 对象。id 和 url 映射接受可选的 iphone、ipad 和 googleplay 键:

layout.js | page.js
export const metadata = {
  twitter: {
    card: 'app',
    app: {
      name: 'Example App',
      id: {
        iphone: '123456789',
        ipad: '123456789',
        googleplay: 'com.example.app',
      },
      url: { iphone: 'https://example.com/app' },
    },
  },
}
字段可接受的输入
id必需的映射。iPhone/iPad ID 接受字符串或数字;Google Play ID 接受字符串。
url可选映射,值为绝对 URL 字符串或 URL 实例
name可选的 string,所有平台共享

Twitter 图片描述符#

Twitter 图片描述符使用与 Open Graph 图片描述符相同的字段:必需的 url 和可选的 alt、secureUrl、type、width 和 height。

viewport#

已弃用:metadata 中的 viewport 选项自 Next.js 14 起已弃用。请改用 viewport 配置。

verification#

verification 支持 google、yahoo、yandex 和 me。每项接受字符串、数字或字符串/数字数组。使用 other 可将其他 meta 名称映射到相同的值形式:

layout.js | page.js
export const metadata = {
  verification: {
    google: 'google',
    yandex: 'yandex',
    yahoo: 'yahoo',
    me: ['my-email', 'my-link'],
    other: {
      'custom-verification': 'custom-token',
    },
  },
}
<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" />
<meta name="custom-verification" content="custom-token" />

appleWebApp#

appleWebApp 配置 web app 元数据,如标题、启动图片和状态栏样式。有关特定平台的行为,请参阅 Apple 的 Safari 元数据参考:

layout.js | page.js
export const metadata = {
  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)',
      },
    ],
  },
}

appleWebApp 接受 true、false 或对象。true 启用 web app 能力;false 省略 Apple web app 元数据。对象字段如下:

字段类型默认值
capableboolean提供对象时为 true
titlestring无
startupImageURL 字符串、{ url: string, media?: string },或其中任一类型的数组无
statusBarStyle'default'、'black' 或 'black-translucent''default'

itunes#

使用 itunes 配置 apple-itunes-app Smart App Banner:

layout.js | page.js
export const metadata = {
  itunes: {
    appId: 'myAppStoreID',
    appArgument: 'myAppArgument',
  },
}
<head> output
<meta
  name="apple-itunes-app"
  content="app-id=myAppStoreID, app-argument=myAppArgument"
/>

appId 是必需的字符串。可选的 appArgument 字符串会使用 metadataBase 和当前路由进行解析。

alternates#

alternates 为规范 URL 和页面的其他版本(如翻译和 RSS feed)添加链接:

layout.js | page.js
export const metadata = {
  alternates: {
    canonical: { url: 'https://nextjs.org', title: 'Next.js' },
    languages: {
      'en-US': 'https://nextjs.org/en-US',
      'de-DE': 'https://nextjs.org/de-DE',
      'x-default': 'https://nextjs.org',
    },
    media: {
      'only screen and (max-width: 600px)': 'https://nextjs.org/mobile',
    },
    types: {
      'application/rss+xml': [
        { url: 'https://nextjs.org/rss', title: 'RSS feed' },
      ],
    },
  },
}
<head> output
<link rel="canonical" href="https://nextjs.org" title="Next.js" />
<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" hreflang="x-default" href="https://nextjs.org" />
<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"
  title="RSS feed"
/>
字段可接受的输入
canonicalURL 字符串、URL 或 `{ url: string \
languages语言代码(包括 'x-default')到 URL 字符串、URL 或描述符数组的映射
media媒体查询到 URL 字符串、URL 或描述符数组的映射
types内容类型到 URL 字符串、URL 或描述符数组的映射

映射中的描述符使用 { url: string | URL, title?: string }。可选的描述符 title 会为链接添加 title 属性。使用数组可为同一映射键提供多个链接。

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

每个平台接受一个描述符或描述符数组。描述符字段如下:

平台必需字段可选字段
ios、iphone、ipadurl(string 或 URL)app_store_id(string 或 number)、app_name(string)
androidpackage(string)url(string 或 URL)、class(string)、app_name(string)
windows_phone、windows、windows_universalurl(string 或 URL)app_id(string)、app_name(string)
weburl(string 或 URL)should_fallback(boolean)

每个字段都会发出 al:<platform>:<field>,例如 al:iphone:app_name 或 al:windows:app_id。

archives#

archives 链接到记录、文档或其他具有历史价值的资料的集合(来源)。它接受字符串或字符串数组。

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

assets#

assets 接受字符串或字符串数组。

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

bookmarks#

bookmarks 接受字符串或字符串数组。

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

pagination#

pagination 链接到序列中的上一页和下一页。其 previous 和 next 字段各接受字符串或 URL,并发出 rel="prev" 和 rel="next" 链接。

layout.js | page.js
export const metadata = {
  pagination: {
    previous: 'https://nextjs.org/blog?page=1',
    next: 'https://nextjs.org/blog?page=3',
  },
}
<head> output
<link rel="prev" href="https://nextjs.org/blog?page=1" />
<link rel="next" href="https://nextjs.org/blog?page=3" />

abstract#

abstract 接受字符串并发出 <meta name="abstract" content="..." />。建议优先使用 description,它取代了此字段。

classification#

classification 接受字符串并发出 <meta name="classification" content="..." />。

category#

category 接受字符串并发出 category meta 标签。

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

facebook#

facebook.appId 接受字符串;facebook.admins 接受字符串或字符串数组。同时提供 appId 和 admins 数组会发出两组标签。有关平台要求,请参阅 Facebook 参考。

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

pinterest#

使用 pinterest.richPin 启用或禁用 Pinterest Rich Pins。它接受布尔值或字符串,并发出 pinterest-rich-pin meta 标签。

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

other#

使用 other 设置自定义命名的 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 对象#

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

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

generateMetadata 函数#

普通函数#

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

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

异步函数#

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

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

带路由段 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) {}

带父级元数据#

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

不支持的 Metadata#

旧版顶级键 apple-touch-fullscreen 和 apple-touch-icon-precomposed 已弃用,不接受值。请分别使用 appleWebApp 和 icons.apple。图标描述符的 rel 是单独的链接属性。

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

Metadata建议
<meta http-equiv="...">通过 redirect()、Proxy、安全请求头使用适当的 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
'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 文档。

tsx
ReactDOM.preload(href: string, options: { as: string })
<head> output
<link rel="preload" href="..." as="..." />

<link rel="preconnect">#

预先建立到某个来源的连接。MDN 文档。

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

<link rel="dns-prefetch">#

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

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

小知识:

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

行为#

默认字段#

即使路由未定义元数据,也始终会添加两个默认的 meta 标签:

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

小知识:你可以使用 viewport 对象或 generateViewport 函数自定义默认的 viewport meta 标签。

流式元数据#

流式元数据允许 Next.js 渲染初始 UI 并将其发送到浏览器,而无需等待 generateMetadata 完成。

当 generateMetadata 解析完成时,生成的元数据标签会附加到 <body> 标签中。我们已经验证,执行 JavaScript 并检查完整 DOM 的机器人(例如 Googlebot)能够正确解析元数据。

对于无法执行 JavaScript 的HTML 受限机器人(例如 facebookexternalhit),Next.js 会在开始响应之前等待 generateMetadata。生成的元数据可在 <head> 标签中找到。generateMetadata 解析后,Next.js 可以开始响应并流式传输剩余的页面内容。

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

要完全禁用流式元数据:

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

const config: NextConfig = {
  htmlLimitedBots: /.*/,
}

export default config
next.config.js
module.exports = {
  htmlLimitedBots: /.*/,
}

流式元数据通过降低 TTFB 来改善感知性能,并有助于降低 LCP 时间。

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

使用 Cache Components#

启用 Cache Components 后,generateMetadata 遵循与其他组件相同的规则。如果元数据访问运行时数据(cookies()、headers()、params、searchParams)或执行未缓存的数据获取,它会延迟到请求时执行。

Next.js 如何处理这一点取决于页面的其余部分:

  • 如果其他部分也延迟到请求时:预渲染会生成静态壳,元数据与其他延迟内容一起流式传输。
  • 如果页面或布局在其他方面完全可预渲染:Next.js 需要显式选择:尽可能缓存数据,或表明延迟渲染是有意的。

在页面其余部分完全可预渲染的情况下,在运行时流式传输元数据并不常见。为确保此行为是有意的,会抛出一个错误,指出需要处理哪个页面或布局。

要解决此问题,你有两个选择。如果元数据依赖外部数据但不依赖运行时数据,请使用 use cache:

app/page.tsx
export async function generateMetadata() {
  'use cache'
  const { title, description } = await db.query('site-metadata')
  return { title, description }
}

如果元数据确实需要运行时数据,请在页面中添加一个动态标记组件:

app/page.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { connection } from 'next/server'

export async function generateMetadata() {
  const token = (await cookies()).get('token')?.value
  // ... 使用 token 获取个性化元数据
  return { title: 'Personalized Title' }
}

const Connection = async () => {
  await connection()
  return null
}

async function DynamicMarker() {
  return (
    <Suspense>
      <Connection />
    </Suspense>
  )
}

export default function Page() {
  // 不要在此处放置 await connection()
  // 否则会阻止 article 标签内容
  // 被包含在静态壳中
  return (
    <>
      <article>Static content</article>
      <DynamicMarker />
    </>
  )
}

DynamicMarker 组件不渲染任何内容,但会告诉 Next.js 该页面包含有意的动态内容。通过将其包裹在 Suspense 中,静态内容仍能正常预渲染。

请参阅 Next.js 在 generateMetadata() 中遇到运行时数据和 Next.js 在 generateMetadata() 中遇到未缓存数据了解完整的修复选项和权衡。

顺序#

元数据按顺序求值,从根路由段开始,一直到最接近最终 page.js 路由段的路由段。例如:

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

合并#

按照求值顺序,同一路由中从多个路由段导出的元数据对象会被浅层合并,形成路由的最终元数据输出。重复的键会根据其顺序被替换。

这意味着在较早路由段中定义的具有嵌套字段的元数据(如 openGraph 和 robots)会被最后定义它们的路由段覆盖。

other 字段是个例外:其自定义标签名称会跨路由段合并。当两个路由段提供相同的自定义标签名称时,后面的值会替换该名称的较早值。

覆盖字段#

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 引入流式支持。
v14.0.0viewport、themeColor 和 colorScheme 已弃用,改用 viewport 配置。
v13.2.0引入 metadata 和 generateMetadata。
Next.js 中文网