NNext.js 中文网 GitHub

元数据与 OG 图片

了解如何为页面添加元数据并创建动态 OG 图片。

Metadata API 可用于定义应用的元数据,以改善 SEO 和网页分享效果,包括:

  1. 静态 metadata 对象
  2. 动态 generateMetadata 函数
  3. 特殊的文件约定,可用于添加静态或动态生成的 favicons 和 OG 图片。

有了上述所有选项,Next.js 会自动为你的页面生成相关的 <head> 标签,你可以在浏览器的开发者工具中查看这些标签。

仅 Server Components 支持导出 metadata 对象和 generateMetadata 函数。

默认字段#

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

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

其他元数据字段可以通过 Metadata 对象(用于静态元数据)或 generateMetadata 函数(用于生成的元数据)来定义。

静态元数据#

要定义静态元数据,请从静态 layout.js 或 page.js 文件中导出一个 Metadata 对象。例如,为 blog 路由添加标题和描述:

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

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

export default function Layout() {}
app/blog/layout.js
export const metadata = {
  title: 'My Blog',
  description: '...',
}

export default function Layout() {}

你可以在 generateMetadata 文档中查看所有可用选项的完整列表。

生成的元数据#

你可以使用 generateMetadata 函数来 fetch 依赖数据的元数据。例如,获取特定博客文章的标题和描述:

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

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

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const slug = (await params).slug

  // 获取文章信息
  const post = await fetch(`https://api.vercel.app/blog/${slug}`).then((res) =>
    res.json()
  )

  return {
    title: post.title,
    description: post.description,
  }
}

export default function Page({ params, searchParams }: Props) {}
app/blog/[slug]/page.js
export async function generateMetadata({ params, searchParams }, parent) {
  const slug = (await params).slug

  // 获取文章信息
  const post = await fetch(`https://api.vercel.app/blog/${slug}`).then((res) =>
    res.json()
  )

  return {
    title: post.title,
    description: post.description,
  }
}

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

流式元数据#

对于动态渲染的页面,Next.js 会单独流式传输元数据,在 generateMetadata 解析后将其注入 HTML,而不会阻塞 UI 渲染。

流式元数据通过让视觉内容优先传输来改善感知性能。

对于期望元数据位于 <head> 标签中的机器人和爬虫(例如 Twitterbot、Slackbot、Bingbot),流式元数据是禁用的。这些是通过传入请求的 User Agent 标头检测到的。

你可以使用 Next.js 配置文件中的 htmlLimitedBots 选项来自定义或完全禁用流式元数据。

预渲染页面不使用流式传输,因为元数据是在构建时解析的。

了解更多关于流式元数据的信息。

记忆化数据请求#

在某些情况下,你需要为元数据和页面本身获取相同的数据。为避免重复请求,你可以使用 React 的 cache 函数来记忆化返回值,只获取数据一次。例如,为元数据和页面获取博客文章信息:

app/lib/data.ts
import { cache } from 'react'
import { db } from '@/app/lib/db'

// getPost 会被使用两次,但只执行一次
export const getPost = cache(async (slug: string) => {
  const res = await db.query.posts.findFirst({ where: eq(posts.slug, slug) })
  return res
})
app/lib/data.js
import { cache } from 'react'
import { db } from '@/app/lib/db'

// getPost 会被使用两次,但只执行一次
export const getPost = cache(async (slug) => {
  const res = await db.query.posts.findFirst({ where: eq(posts.slug, slug) })
  return res
})
app/blog/[slug]/page.tsx
import { getPost } from '@/app/lib/data'

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  return {
    title: post.title,
    description: post.description,
  }
}

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  return <div>{post.title}</div>
}
app/blog/[slug]/page.js
import { getPost } from '@/app/lib/data'

export async function generateMetadata({ params }) {
  const { slug } = await params
  const post = await getPost(slug)
  return {
    title: post.title,
    description: post.description,
  }
}

export default async function Page({ params }) {
  const { slug } = await params
  const post = await getPost(slug)
  return <div>{post.title}</div>
}

基于文件的元数据#

以下特殊文件可用于元数据:

你可以将这些用于静态元数据,也可以用代码以编程方式生成这些文件。

Favicons#

Favicon 是在书签和搜索结果中代表你网站的小图标。要为应用添加 favicon,请创建一个 favicon.ico 并将其添加到 app 文件夹的根目录。

你也可以使用代码以编程方式生成 favicon。有关更多信息,请参阅 favicon 文档。

静态 Open Graph 图片#

Open Graph (OG) 图片是在社交媒体中代表你网站的图片。要为应用添加静态 OG 图片,请在 app 文件夹的根目录创建一个 opengraph-image.jpg 文件。

你还可以通过在文件夹结构的更深处创建 opengraph-image.jpg 来为特定路由添加 OG 图片。例如,要创建特定于 /blog 路由的 OG 图片,请在 blog 文件夹中添加一个 opengraph-image.jpg 文件。

更具体的图片将优先于文件夹结构中位于其上方的任何 OG 图片。

也支持其他图片格式,如 jpeg、png 和 gif。有关更多信息,请参阅 Open Graph 图片文档。

生成的 Open Graph 图片#

ImageResponse 构造函数允许你使用 JSX 和 CSS 生成动态图片。这适用于依赖数据的 OG 图片。

例如,要为每篇博客文章生成独特的 OG 图片,请在 blog/[slug] 文件夹中添加一个 opengraph-image.tsx 文件,并从 next/og 导入 ImageResponse 构造函数:

app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { getPost } from '@/app/lib/data'

// 图片元数据
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// 图片生成
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)

  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    )
  )
}
app/blog/[slug]/opengraph-image.js
import { ImageResponse } from 'next/og'
import { getPost } from '@/app/lib/data'

// 图片元数据
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// 图片生成
export default async function Image({ params }) {
  const { slug } = await params
  const post = await getPost(slug)

  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    )
  )
}

ImageResponse 支持常见的 CSS 属性,包括 flexbox 和绝对定位、自定义字体、文本换行、居中和嵌套图片。查看支持的 CSS 属性的完整列表。

小知识:

  • 示例可在 Vercel OG Playground 中查看。
  • ImageResponse 使用 @vercel/og、satori 和 resvg 将 HTML 和 CSS 转换为 PNG。
  • 仅支持 flexbox 和一部分 CSS 属性。高级布局(例如 display: grid)将无法工作。
Next.js 中文网