
Next.js 通过自动读取 Layout.js 中导出的 metadata 对象(或 generateMetadata 函数),为整个应用注入标准化的 HTML 元数据,无需手动导入或调用。
next.js 通过自动读取 `layout.js` 中导出的 `metadata` 对象(或 `generatemetadata` 函数),为整个应用注入标准化的 html `
` 元数据,无需手动导入或调用。在 Next.js App Router 中,metadata 并非普通变量,而是一个约定式导出(convention-based export)——它被框架深度集成于渲染生命周期中。当你在 app/layout.js(或 app/layout.tsx)中写:
export const metadata = {
title: "NextJS App",
description: "Your first NextJS app!",
};Next.js 会在构建和运行时自动识别该导出,并将其序列化为标准 HTML 标签,例如:
<head> <title>NextJS App</title> <meta name="description" content="Your first NextJS app!" /> </head>
✅ 关键机制说明:
使用 extruct 从原始 HTML 中提取机器可读的元数据,以便代理可以在不依赖脆弱的全页解析的情况下对页面进行分类、去重或丰富。它最适合元数据采集工作流,而不适用于爬取整个网站或渲染 JavaScript 密集型页面。
- ✅ 零导入、零调用:你无需
import { metadata } from './layout',也不需要在组件中使用它——Next.js 会主动扫描布局文件的顶层导出; - ✅ 作用域继承:根布局(
app/layout.js)中的metadata会作为默认元数据应用于所有子路由页面,除非子页面(如app/dashboard/layout.js或app/about/page.js)显式覆盖; - ✅ 支持动态与静态混合:除静态对象外,你也可导出异步函数
generateMetadata(),用于基于params、searchParams或外部 API 动态生成标题、 Open Graph 图片等:
export async function generateMetadata({ params }) {
const post = await fetchPost(params.id);
return {
title: post.title,
openGraph: {
images: [post.ogImage],
},
};
}⚠️ 注意事项:
-
metadata仅在layout.js/ts、page.js/ts、route.js/ts等 App Router 特定文件中生效,普通组件中导出无效; - 若同时定义了
metadata和generateMetadata,后者优先; - 所有字段均遵循 Next.js 元数据规范,如
icons、appleWebApp、twitter等可直接增强 SEO 与社交分享体验。
简言之:这不是“被遗忘的变量”,而是 Next.js 为开发者提供的声明式元数据基础设施——你只需“写出来”,框架负责“用起来”。

















