元數據

Next.js 提供了一個 Metadata API，可用於定義應用程式的元數據（例如 HTML head 元素中的 meta 和 link 標籤），以提升 SEO 和網頁分享效果。

您可以通過兩種方式為應用程式添加元數據：

基於配置的元數據：在 layout.js 或 page.js 文件中導出一個靜態 metadata 物件或動態的 generateMetadata 函數。
基於檔案的元數據：在路由段中添加靜態或動態生成的特殊檔案。

無論使用哪種方式，Next.js 都會自動為您的頁面生成相關的 <head> 元素。您還可以使用 ImageResponse 構造函數創建動態 OG 圖片。

靜態元數據

要定義靜態元數據，請從 layout.js 或靜態 page.js 文件中導出一個 Metadata 物件。

import type { Metadata } from 'next'

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

export default function Page() {}

有關所有可用選項，請參閱 API 參考。

動態元數據

您可以使用 generateMetadata 函數來獲取需要動態值的元數據。

import type { Metadata, ResolvingMetadata } from 'next'

type Props = {
  params: { id: string }
  searchParams: { [key: string]: string | string[] | undefined }
}

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  // 讀取路由參數
  const id = params.id

  // 獲取數據
  const product = await fetch(`https://.../${id}`).then((res) => res.json())

  // 可選地訪問並擴展（而非替換）父元數據
  const previousImages = (await parent).openGraph?.images || []

  return {
    title: product.title,
    openGraph: {
      images: ['/some-specific-page-image.jpg', ...previousImages],
    },
  }
}

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

有關所有可用參數，請參閱 API 參考。

須知：

通過 generateMetadata 生成的靜態和動態元數據僅在伺服器組件中受支援。

fetch 請求會自動記憶化，以便在 generateMetadata、generateStaticParams、佈局、頁面和伺服器組件之間共享相同數據。如果無法使用 fetch，可以使用 React 的 cache。

Next.js 會等待 generateMetadata 內的數據獲取完成後，再將 UI 串流到客戶端。這確保了串流響應的第一部分包含 <head> 標籤。

基於檔案的元數據

以下特殊檔案可用於元數據：

您可以將這些檔案用於靜態元數據，也可以通過代碼動態生成這些檔案。

有關實現和示例，請參閱 Metadata Files API 參考和動態圖片生成。

行為

基於檔案的元數據具有更高的優先級，會覆蓋任何基於配置的元數據。

默認字段

即使路由未定義元數據，也會始終添加兩個默認的 meta 標籤：

meta charset 標籤設置網站的字符編碼。
meta viewport 標籤設置網站的視口寬度和縮放比例，以適應不同設備。

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

須知：您可以覆蓋默認的 viewport meta 標籤。

順序

元數據的評估順序是從根段開始，一直到最接近最終 page.js 的段。例如：

app/layout.tsx (根佈局)
app/blog/layout.tsx (嵌套的部落格佈局)
app/blog/[slug]/page.tsx (部落格頁面)

合併

根據評估順序，同一路由中多個段導出的 Metadata 物件會淺合併，形成路由的最終元數據輸出。重複的鍵會根據順序被替換。

這意味著具有嵌套字段的元數據（如 openGraph 和 robots）如果在較早的段中定義，會被最後一個定義它們的段覆蓋。

覆蓋字段

app/layout.js

export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}

app/blog/page.js

export const metadata = {
  title: 'Blog',
  openGraph: {
    title: 'Blog',
  },
}

// 輸出：
// <title>Blog</title>
// <meta property="og:title" content="Blog" />

在上面的示例中：

app/layout.js 中的 title 被 app/blog/page.js 中的 title 替換。
app/layout.js 中的所有 openGraph 字段在 app/blog/page.js 中被替換，因為 app/blog/page.js 設置了 openGraph 元數據。注意 openGraph.description 的缺失。

如果您希望在覆蓋某些字段的同時共享一些嵌套字段，可以將它們提取到單獨的變量中：

app/shared-metadata.js

export const openGraphImage = { images: ['http://...'] }

app/page.js

import { openGraphImage } from './shared-metadata'

export const metadata = {
  openGraph: {
    ...openGraphImage,
    title: 'Home',
  },
}

app/about/page.js

import { openGraphImage } from '../shared-metadata'

export const metadata = {
  openGraph: {
    ...openGraphImage,
    title: 'About',
  },
}

在上面的示例中，OG 圖片在 app/layout.js 和 app/about/page.js 之間共享，而標題則不同。

繼承字段

app/layout.js

export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}

app/about/page.js

export const metadata = {
  title: 'About',
}

// 輸出：
// <title>About</title>
// <meta property="og:title" content="Acme" />
// <meta property="og:description" content="Acme is a..." />

注意

app/layout.js 中的 title 被 app/about/page.js 中的 title 替換。
app/layout.js 中的所有 openGraph 字段在 app/about/page.js 中被繼承，因為 app/about/page.js 未設置 openGraph 元數據。

動態圖片生成

ImageResponse 構造函數允許您使用 JSX 和 CSS 生成動態圖片。這對於創建社交媒體圖片（如 Open Graph 圖片、Twitter 卡片等）非常有用。

ImageResponse 使用 Edge Runtime，Next.js 會自動為緩存的圖片添加正確的標頭，有助於提高性能並減少重新計算。

要使用它，可以從 next/og 導入 ImageResponse：

app/about/route.js

import { ImageResponse } from 'next/og'

export const runtime = 'edge'

export async function GET() {
  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          textAlign: 'center',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        Hello world!
      </div>
    ),
    {
      width: 1200,
      height: 600,
    }
  )
}

ImageResponse 與其他 Next.js API（包括 Route Handlers 和基於檔案的元數據）很好地集成。例如，您可以在 opengraph-image.tsx 文件中使用 ImageResponse 在構建時或請求時動態生成 Open Graph 圖片。

ImageResponse 支援常見的 CSS 屬性，包括 flexbox 和絕對定位、自定義字體、文本換行、居中以及嵌套圖片。查看支援的 CSS 屬性完整列表。

須知：

示例可在 Vercel OG Playground 中查看。

ImageResponse 使用 @vercel/og、Satori 和 Resvg 將 HTML 和 CSS 轉換為 PNG。

僅支援 Edge Runtime。默認的 Node.js 運行時無效。

僅支援 flexbox 和部分 CSS 屬性。高級佈局（如 display: grid）無效。

最大捆綁大小為 500KB。捆綁大小包括您的 JSX、CSS、字體、圖片和其他資源。如果超過限制，請考慮減小資源大小或在運行時獲取。

僅支援 ttf、otf 和 woff 字體格式。為了最大化字體解析速度，優先使用 ttf 或 otf 而非 woff。

JSON-LD

JSON-LD 是一種結構化數據格式，可以被搜索引擎用來理解您的內容。例如，您可以用它來描述一個人、事件、組織、電影、書籍、食譜等許多類型的實體。

目前我們建議在 layout.js 或 page.js 組件中將結構化數據渲染為 <script> 標籤。例如：

export default async function Page({ params }) {
  const product = await getProduct(params.id)

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    image: product.image,
    description: product.description,
  }

  return (
    <section>
      {/* 將 JSON-LD 添加到頁面 */}
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      {/* ... */}
    </section>
  )
}

您可以使用 Rich Results Test（Google）或通用的 Schema Markup Validator 來驗證和測試結構化數據。

您可以使用社區包（如 schema-dts）來為 JSON-LD 添加 TypeScript 類型：

import { Product, WithContext } from 'schema-dts'

const jsonLd: WithContext<Product> = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  name: 'Next.js Sticker',
  image: 'https://nextjs.org/imgs/sticker.png',
  description: 'Dynamic at the speed of static.',
}

generateMetadata

中繼資料檔案

generateViewport

On this page