opengraph-image 與 twitter-image

opengraph-image 和 twitter-image 檔案規範允許您為路由區段設定 Open Graph 和 Twitter 圖片。

這些規範對於設定當使用者在社交網路和通訊應用程式中分享您網站連結時顯示的圖片非常有用。

設定 Open Graph 和 Twitter 圖片有兩種方式：

使用圖片檔案 (.jpg, .png, .gif)
使用程式碼生成圖片 (.js, .ts, .tsx)

圖片檔案 (.jpg, .png, .gif)

透過在路由區段放置 opengraph-image 或 twitter-image 圖片檔案，可以設定該區段的分享圖片。

Next.js 會評估該檔案並自動將適當的標籤添加到應用程式的 <head> 元素中。

檔案規範	支援的檔案類型
`opengraph-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`twitter-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`opengraph-image.alt`	`.txt`
`twitter-image.alt`	`.txt`

須知：

twitter-image 檔案大小不得超過 5MB，而 opengraph-image 檔案大小不得超過 8MB。如果圖片檔案大小超過這些限制，建置將會失敗。

`opengraph-image`

在任何路由區段添加 opengraph-image.(jpg|jpeg|png|gif) 圖片檔案。

<head> 輸出

<meta property="og:image" content="<generated>" />
<meta property="og:image:type" content="<generated>" />
<meta property="og:image:width" content="<generated>" />
<meta property="og:image:height" content="<generated>" />

`twitter-image`

在任何路由區段添加 twitter-image.(jpg|jpeg|png|gif) 圖片檔案。

<head> 輸出

<meta name="twitter:image" content="<generated>" />
<meta name="twitter:image:type" content="<generated>" />
<meta name="twitter:image:width" content="<generated>" />
<meta name="twitter:image:height" content="<generated>" />

`opengraph-image.alt.txt`

在與 opengraph-image.(jpg|jpeg|png|gif) 圖片相同的路由區段中，添加一個 opengraph-image.alt.txt 檔案作為其替代文字。

opengraph-image.alt.txt

關於 Acme

<head> 輸出

<meta property="og:image:alt" content="關於 Acme" />

`twitter-image.alt.txt`

在與 twitter-image.(jpg|jpeg|png|gif) 圖片相同的路由區段中，添加一個 twitter-image.alt.txt 檔案作為其替代文字。

twitter-image.alt.txt

關於 Acme

<head> 輸出

<meta property="twitter:image:alt" content="關於 Acme" />

使用程式碼生成圖片 (.js, .ts, .tsx)

除了使用實際圖片檔案外，您還可以使用程式碼動態生成圖片。

透過創建一個預設導出函數的 opengraph-image 或 twitter-image 路由，生成路由區段的分享圖片。

檔案規範	支援的檔案類型
`opengraph-image`	`.js`, `.ts`, `.tsx`
`twitter-image`	`.js`, `.ts`, `.tsx`

須知：

預設情況下，生成的圖片會進行靜態優化（在建置時生成並快取），除非它們使用了動態 API 或未快取的資料。

您可以使用 generateImageMetadata 在同一個檔案中生成多張圖片。

opengraph-image.js 和 twitter-image.js 是特殊的路由處理器，預設會快取，除非使用了動態 API 或動態配置選項。

生成圖片最簡單的方法是使用 next/og 提供的 ImageResponse API。

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// 圖片元資料
export const alt = '關於 Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// 圖片生成
export default async function Image() {
  // 字體載入，process.cwd() 是 Next.js 專案目錄
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        關於 Acme
      </div>
    ),
    // ImageResponse 選項
    {
      // 為方便起見，我們可以重複使用導出的 opengraph-image
      // 尺寸配置來設定 ImageResponse 的寬度和高度。
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// 圖片元資料
export const alt = '關於 Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// 圖片生成
export default async function Image() {
  // 字體載入，process.cwd() 是 Next.js 專案目錄
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        關於 Acme
      </div>
    ),
    // ImageResponse 選項
    {
      // 為方便起見，我們可以重複使用導出的 opengraph-image
      // 尺寸配置來設定 ImageResponse 的寬度和高度。
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

<head> 輸出

<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="關於 Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

屬性

預設導出函數會接收以下屬性：

`params` (選用)

一個物件，包含從根區段到 opengraph-image 或 twitter-image 所在區段的動態路由參數物件。

export default function Image({ params }: { params: { slug: string } }) {
  // ...
}

export default function Image({ params }) {
  // ...
}

路由	URL	`params`
`app/shop/opengraph-image.js`	`/shop`	`undefined`
`app/shop/[slug]/opengraph-image.js`	`/shop/1`	`{ slug: '1' }`
`app/shop/[tag]/[item]/opengraph-image.js`	`/shop/1/2`	`{ tag: '1', item: '2' }`

返回值

須知：ImageResponse 符合此返回類型。

配置導出

您可以選擇性地從 opengraph-image 或 twitter-image 路由導出 alt、size 和 contentType 變數來配置圖片的元資料。

選項	類型
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - 圖片 MIME 類型

`alt`

export const alt = '我的圖片替代文字'

export default function Image() {}

export const alt = '我的圖片替代文字'

export default function Image() {}

<head> 輸出

<meta property="og:image:alt" content="我的圖片替代文字" />

`size`

export const size = { width: 1200, height: 630 }

export default function Image() {}

export const size = { width: 1200, height: 630 }

export default function Image() {}

<head> 輸出

<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

`contentType`

export const contentType = 'image/png'

export default function Image() {}

export const contentType = 'image/png'

export default function Image() {}

<head> 輸出

<meta property="og:image:type" content="image/png" />

路由區段配置

opengraph-image 和 twitter-image 是專門的路由處理器，可以使用與頁面和佈局相同的路由區段配置選項。

範例

使用外部資料

此範例使用 params 物件和外部資料來生成圖片。

須知：預設情況下，此生成的圖片會進行靜態優化。您可以配置個別的 fetch 選項 或路由區段選項來改變此行為。

import { ImageResponse } from 'next/og'

export const alt = '關於 Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

import { ImageResponse } from 'next/og'

export const alt = '關於 Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }) {
  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

使用 Node.js 執行環境與本地資源

此範例使用 Node.js 執行環境來獲取檔案系統上的本地圖片，並將其作為 ArrayBuffer 傳遞給 <img> 元素的 src 屬性。本地資源應相對於專案的根目錄放置，而不是範例原始檔的位置。

import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

版本歷史

版本	變更內容
`v13.3.0`	引入 `opengraph-image` 和 `twitter-image`。

On this page