React / 系统课时

配置页面元数据

配置页面元数据

本课将使用 App Router 的 Metadata API 设置页面标题、描述和社交分享信息。完成后,浏览器标签、搜索摘要以及 Open Graph 和 Twitter 卡片都能从同一份类型安全配置生成。

学习目标

  • 在布局和页面中导出静态元数据
  • 使用标题模板统一站点名称
  • 验证最终生成的 head 内容

在根布局定义公共规则

根布局适合声明站点级标题模板和基础描述。metadataBase 用于把相对资源地址解析为绝对地址。

tsx
import type { Metadata } from 'next'
import type { ReactNode } from 'react'

export const metadata: Metadata = {
  metadataBase: new URL(
    process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000',
  ),
  title: {
    default: 'Anystack 学习平台',
    template: '%s | Anystack',
  },
  description: '面向开发者的系统化技术课程。',
}

export default function RootLayout({
  children,
}: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  )
}

生效行为:没有单独标题的页面使用默认标题;子页面提供标题后,模板会自动追加站点名称。生产环境应把 NEXT_PUBLIC_SITE_URL 设置为真实站点源地址。

为页面补充分享信息

页面可以覆盖或扩展父布局元数据。下面假设 /og/nextjs-course.png 已放在 public/og/ 中。

tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Next.js 全栈开发教程',
  description: '从 App Router 开始学习 Next.js 页面、数据与缓存。',
  openGraph: {
    title: 'Next.js 全栈开发教程',
    description: '从 App Router 开始学习 Next.js 页面、数据与缓存。',
    type: 'website',
    images: [
      {
        url: '/og/nextjs-course.png',
        width: 1200,
        height: 630,
        alt: 'Next.js 全栈开发教程',
      },
    ],
  },
  twitter: {
    card: 'summary_large_image',
    title: 'Next.js 全栈开发教程',
    description: '从 App Router 开始学习 Next.js 页面、数据与缓存。',
    images: ['/og/nextjs-course.png'],
  },
}

export default function CoursePage() {
  return <main><h1>Next.js 全栈开发教程</h1></main>
}

预期结果:浏览器标题显示为“Next.js 全栈开发教程 | Anystack”,页面源代码中包含描述、Open Graph 和 Twitter 对应的元标签,分享图地址会基于 metadataBase 解析。

处理动态元数据与常见问题

动态页面使用 generateMetadata

商品、文章等动态详情页可以导出异步 generateMetadata。它应复用页面数据读取函数,并对不存在的数据返回安全标题,而不是在元数据阶段抛出难以理解的错误。

ts
import type { Metadata } from 'next'

type Props = {
  params: Promise<{ slug: string }>
}

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

  return {
    title: `课程:${slug}`,
    description: `查看课程 ${slug} 的学习内容。`,
  }
}

这是片段示例。真实项目应把 slug 转换为课程数据并处理不存在的记录。验证时访问两个不同详情地址,确认标题和描述随参数变化。

避免常见配置问题

不要在普通客户端组件中导出 Metadata API。元数据应由布局、页面或对应的元数据文件在服务端生成。

标题和描述应与页面实际内容一致。分享图需要稳定的公开地址和适合社交卡片的尺寸;文件不存在或 metadataBase 错误时,预览工具会得到无效图片地址。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置页面元数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通