[!info] related notes

• 所属 MOC: nextjs-moc
• 前置概念: html-meta-and-seo、nextjs-dynamic-route-segments
• 并列概念:
• 易混淆概念:
• 关系笔记: nextjs-mdx-static-content

Next.js Metadata API

一句话定义

Next.js Metadata API 是 App Router 中声明页面 <head> 元信息的框架接口，可以为每个 route 生成 title、description、canonical、Open Graph、robots、icons、sitemap 等元数据。

三种主要来源

static metadata object
→ 已知且固定的页面元信息

generateMetadata()
→ 根据 params / data 动态生成

file conventions
→ favicon / opengraph-image / robots / sitemap 等

静态 Metadata

export const metadata = {
  title: 'Goals',
  description: 'Manage your goals',
}

适合 About、Dashboard 首页等不依赖运行时实体的页面。

generateMetadata()

动态详情页通常需要根据 route parameter 和服务器数据生成 metadata：

/blog/[slug]
→ params.slug
→ getPost(slug)
→ generateMetadata()
→ title / description / social preview

它解决的是：

页面本身是动态实体时，<head> 如何和这个实体保持一致？

而不是让客户端 useEffect 在页面加载后再改标题。

为什么 Metadata 应尽量在服务器/预渲染阶段得到

搜索引擎、社交分享抓取器和浏览器在解析页面时需要尽早看到：

• title
• description
• canonical
• Open Graph
• robots directives

所以：

HTML / server-rendered metadata
→ crawler can understand immediately

client-only post-render mutation
→ 对 SEO / crawler 更不稳定

Metadata 继承

Layout 可以提供站点级默认值，子 route 覆盖局部字段：

Root Layout
→ default site title / description

Blog Layout
→ blog-specific defaults

Post Page
→ post-specific metadata

常见做法是使用 title template：

%s | Product Name

避免每个页面手工重复品牌后缀。

File-based Metadata

App Router 可以用文件约定表达一些 metadata 资源：

favicon.ico
icon.*
opengraph-image.*
twitter-image.*
robots.txt / robots.ts
sitemap.xml / sitemap.ts

这让“静态文件”也成为路由/构建模型的一部分。

Open Graph 与 SEO 不是同一个东西

SEO metadata
→ 帮助搜索引擎理解 / 展示页面

Open Graph / social metadata
→ 控制链接在社交平台和聊天工具里的预览

它们相关，但不能把“有 OG 图”理解成“搜索排名自动提升”。

Dynamic Metadata 的边界

Metadata 生成也属于服务器数据读取，需要考虑：

• 数据 owner
• 缓存
• 失败/404
• 重复查询

不要为了 title 单独绕一次内部 HTTP API；与页面读取相同实体时，应复用合理的数据访问边界和缓存策略。

Metadata 与正文是两个输出面

Route Data
├─→ page UI
└─→ metadata

两边都应该来自同一个 authoritative entity，但输出目的不同。

最短记忆

metadata = static route metadata
generateMetadata = data-dependent route metadata
file conventions = icon / OG / robots / sitemap

Metadata API
→ server/framework head generation
≠ client useEffect title patch

Open Graph
≠ SEO ranking itself