> For the complete documentation index, see [llms.txt](https://onenesss-organization.gitbook.io/jj-xiaoce/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onenesss-organization.gitbook.io/jj-xiaoce/next.js-kai-fa-zhi-nan/24.-metadata-pian-ji-yu-pei-zhi.md).
# 24. Metadata 篇 ❘ 基于配置
### 前言
Metadata，中文译为“元数据”，简单的来说就是描述数据的数据。
例如，一个 HTML 文件是一种数据，但 HTML 文件也能在 `` 元素中包含描述该文档的数据，比如该文件的标题和字符编码。这些数据就被称为“元数据”。
```html
我的测试页面
```
不止标题和字符编码，元数据是一个非常丰富的概念，`` 中的各种 meta 标签都是元数据，比如这是描述文档作者和文档信息的元数据：
```html
```
这是根据 [Open Graph 协议](https://ogp.me/)编写的元数据，当分享到诸如 Facebook 这样的社交平台的时候，会展示特殊的格式和信息：
```javascript
```
网站的自定义图标、`robots.txt`、`sitemap.xml` 等也是元数据：
```html
```
元数据的丰富会改善 SEO 和 web 可共享性（比如定义一些特殊的字段用于内容分享到一些社交平台），为了方便定义和管理这些元数据，Next.js 提供了 Metadata API。在 Next.js 中，添加元数据的方法分为两类：
1. 基于配置的元数据：在 `layout.js`或 `page.js`中导出一个静态 `metadata` 对象或者一个动态的 `generateMetadata` 函数。
2. 基于文件的元数据：添加一个静态或者动态生成的特殊文件
通过这些选项，Next.js 会自动为页面生成相关的 `` 元素。
### 1. 基于配置（Config-based）
#### 1.1. 静态元数据
要定义一个静态元数据，需要从 `layout.js` 或者 `page.js` 文件中导出一个 `Metadata` 对象：
```javascript
// layout.js | page.js
export const metadata = {
title: '...',
description: '...',
}
export default function Page() {}
```
具体 Metadata 对象有哪些字段呢？我数了数[源码中的字段](https://github.com/vercel/next.js/blob/canary/packages/next/src/lib/metadata/default-metadata.tsx)，有 31 个，因为内容很多，所以放在本篇后面具体讲解。我们先了解下主要的定义元数据的方式。
#### 1.2. 动态元数据
动态元数据是指依赖动态信息如当前路由参数、外部数据、父级路由段`metadata`等信息的元数据。要定义动态元数据，需要导出一个名为 `generateMetadata`的函数，该函数返回一个 Metadata 对象。使用示例如下：
```javascript
// app/products/[id]/page.js
export async function generateMetadata({ params, searchParams }, parent) {
// 读取路由参数
const id = params.id
// 获取数据
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 }) {}
```
让我们详细讲解下 generateMetadata 函数。该函数接收两个参数，`props` 和 `parent`。
`props` 指的是包含当前路由参数的对象，该对象又有两个字段，一个是 `params`，一个是 `searchParams`。
* params 包含当前动态路由参数的对象，让我们举些例子你就知道了:
| **Route** | **URL** | **params** |
| ------------------------------- | --------- | ----------------------- |
| 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'] } |
那如果访问的不是动态路由呢？那 params 就是一个空对象 `{}`。
* `searchParams` 是一个包含当前 URL 搜索参数的对象，举个例子：
| **URL 网址** | **searchParams** |
| -------------- | ------------------ |
| /shop?a=1 | { a: '1' } |
| /shop?a=1\&b=2 | { a: '1', b: '2' } |
| /shop?a=1\&a=2 | { a: \['1', '2'] } |
`searchParams` 只在 `page.js` 中会有。
而 `parent` 是一个包含父路由段 metadata 对象的 promise 对象，所以示例代码中用的是 `(await parent).openGraph`获取。
注意：无论是静态元数据还是动态元数据**都只在服务端组件中支持**。如果不依赖运行时的信息，则应该尽可能使用静态元数据方式。
缓存篇里也会讲，在 `generateMetadata`、`generateStaticParams`、布局、页面和服务端组件中的 fetch 请求会自动记忆化，所以不用担心多次请求有性能损失。
Next.js 会在等待 `generateMetadata`中数据请求完毕再开始 UI 流式传输给客户端，这可以保证流式响应的第一部分包含 `` 标签。
### 2. 基于文件（File-based）
这些特殊的文件都可用于元数据：
* favicon.ico、apple-icon.jpg 和 icon.jpg
* opengraph-image.jpg 和 twitter-image.jpg
* robots.txt
* sitemap.xml
基于文件是什么意思呢？我们以 icon 为例，icon 被用于设置浏览器网页标签的图标，虽然也可以使用静态元数据的方式设置（具体讲 metadata 对象的时候会讲到），但是 Next.js 提供了更便捷的方式，那就是约定一个文件名为 `icon` 的图片，格式支持 `.ico`、`.jpg`, `.jpeg`, `.png`, `.svg`。也就是添加一个名为 `icon.(ico|jpg|jpeg|png|svg)`的图片，Next.js 就会为该路由生成对应的元数据标签：
```html
```
甚至如果你想动态生成该图片也可以实现，约定一个名为 `icon.(js|.ts|.tsx)`的文件，返回一张图片即可。
其他文件也是同理，使用这种方式快捷直观。不过具体这些文件该怎么设置，因为涉及的 API 太多，统一放在后面讲解。
要注意：基于文件的元数据具有更高的优先级，并会覆盖任何基于配置的元数据。
### 3. 行为
#### 3.1. 默认字段
有两个默认的 `meta` 标签，即使路由未定义元数据也会添加，一个是设置网站字符编码的 `charset`，一个是设置网站视口宽度和比例的 `viewport`：
```html
```
当然这两个元数据标签也都是可以覆盖的。
#### 3.2. 顺序
一个页面和它的布局以及它的父布局，都设置了一些元数据字段，有的字段重复，有的字段不同，那么 Next.js 该怎么处理呢？
这个逻辑其实我们也很容易想到，具体页面的设置应该优先级更高。Next.js 就是按照从根路由到 `page.js`的顺序处理，比如当你访问 `/blog/1`，处理顺序为：
1. `app/layout.tsx`（根布局）
2. `app/blog/layout.tsx`（嵌套布局布局）
3. `app/blog/[slug]/page.tsx`（具体页面）
#### 3.3. 字段覆盖
Next.js 会按照这个顺序，将各层元数据对象**浅合并**，计算得到最终的元数据。重复的将会根据顺序进行替换。让我们举个例子，加入根布局的 `metadata` 设置为：
```javascript
// app/layout.js
export const metadata = {
title: 'Acme',
openGraph: {
title: 'Acme',
description: 'Acme is a...',
},
}
```
`page.js` 的设置为：
```javascript
// app/blog/page.js
export const metadata = {
title: 'Blog',
openGraph: {
title: 'Blog',
},
}
// 输出:
// Blog
//
```
在这个例子中：
1. `app/layout.js` 中的 `title` 被 `app/blog/page.js` 中的 `title` 替换
2. `app/layout.js` 中的 `openGraph` 字段被 `app/blog/page.js` 中的 `openGraph` 替换，注意因为是浅合并，所以 `description` 字段丢失了。
如果你想在多个路由之间共享一些字段，那你可以将他们提取到一个单独的变量中，比如在 `app`下建立一个 `shared-metadata.js`文件共享的字段：
```javascript
// app/shared-metadata.js
export const openGraphImage = { images: ['http://...'] }
```
当需要使用时：
```javascript
// app/page.js
import { openGraphImage } from './shared-metadata'
export const metadata = {
openGraph: {
...openGraphImage,
title: 'Home',
},
}
```
```javascript
// app/about/page.js
import { openGraphImage } from '../shared-metadata'
export const metadata = {
openGraph: {
...openGraphImage,
title: 'About',
},
}
```
在这个例子中，OG 图片在 `app/layout.js` 和 `app/about/page.js` 中共享，然而 `title` 却是不同的。
#### 3.4. 字段继承
比如根布局的设置为：
```javascript
// app/layout.js
export const metadata = {
title: 'Acme',
openGraph: {
title: 'Acme',
description: 'Acme is a...',
},
}
```
页面的设置为：
```javascript
// app/about/page.js
export const metadata = {
title: 'About',
}
// 输出:
// About
//
//
```
在这个例子中：
* `app/layout.js` 中的 `title` 被 `app/about/page.js` 中的 `title` 替代
* `app/layout.js` 中的所有 `openGraph` 字段被 `app/about/page.js` 继承，因为 `app/about/page.js` 没有设置 `openGraph` 字段
### 4. JSON-LD
#### 4.1 介绍
JSON-LD，英文全称：`JavaScript Object Notation for Linked Data`，当然这个太“全”了，稍微简写一点就是 `JSON for Linking Data`，官方文档地址：[json-ld.org/](https://link.juejin.cn?target=https%3A%2F%2Fjson-ld.org%2F)，是一种基于 JSON 的数据格式，用于向 Google 和其他搜索引擎描述网站上的内容。
比如如果我们在 Google 搜索 「Chocolate in a mug」，我们会看到这样的搜索结果：
这个搜索结果有评分（4.5）、评价（581条）等内容，我们打开页面，就可以看到搜索展示的这个内容其实对应了 `application/ld+json` 中的内容：
#### 4.2 正常添加
如果我们也要实现这样的效果，方便搜索引擎展现，该怎么做呢？
在页面加入这种结构化数据的方法很简单，只用在页面添加这样一段脚本就可以了：
```html
```
具体里面的内容需要参考比如 Google 搜索中心提供的[《结构化数据常规指南》](https://link.juejin.cn?target=https%3A%2F%2Fdevelopers.google.com%2Fsearch%2Fdocs%2Fadvanced%2Fstructured-data%2Fsd-policies)，如果你写的是文章，参考 [Article 章节](https://link.juejin.cn?target=https%3A%2F%2Fdevelopers.google.com%2Fsearch%2Fdocs%2Fadvanced%2Fstructured-data%2Farticle)后，可以写入以下这些属性：
```html
```
#### 4.3 Next.js 添加
如何在 Next.js 中添加 JOSN-LD 呢？Next.js 推荐在 `layout.js`或 `page.js`组件中使用 `