跳到內容
檔案系統約定元資料檔案opengraph-image 和 twitter-image

opengraph-image 和 twitter-image

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

當用戶分享指向您網站的連結時，它們對於設定出現在社交網路和訊息應用程式上的圖片非常有用。

有兩種方法可以設定 Open Graph 和 Twitter 圖片

圖片檔案（.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 檔案作為其 alt 文字。

opengraph-image.alt.txt
About Acme
<head> 輸出
<meta property="og:image:alt" content="About Acme" />

twitter-image.alt.txt

在與 twitter-image.(jpg|jpeg|png|gif) 圖片相同的路由段中新增一個附帶的 twitter-image.alt.txt 檔案作為其 alt 文字。

twitter-image.alt.txt
About Acme
<head> 輸出
<meta property="twitter:image:alt" content="About 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。

app/about/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
// Image metadata
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
 
export const contentType = 'image/png'
 
// Image generation
export default async function Image() {
  // Font loading, process.cwd() is Next.js project directory
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )
 
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        About Acme
      </div>
    ),
    // ImageResponse options
    {
      // For convenience, we can re-use the exported opengraph-image
      // size config to also set the ImageResponse's width and height.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}
<head> 輸出
<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="About Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

屬性

預設匯出函式接收以下 props

params (可選)

一個 Promise，它解析為一個物件，其中包含從根段到 opengraph-image 或 twitter-image 所在的段的動態路由引數物件。

須知：如果您使用 generateImageMetadata，函式還將接收一個 id prop，該 prop 是一個 Promise，解析為 generateImageMetadata 返回的專案之一的 id 值。

app/shop/[slug]/opengraph-image.tsx
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}
路由URLparams
app/shop/opengraph-image.js/shopundefined
app/shop/[slug]/opengraph-image.js/shop/1Promise<{ slug: '1' }>
app/shop/[tag]/[item]/opengraph-image.js/shop/1/2Promise<{ tag: '1', item: '2' }>

返回

預設匯出函式應返回 Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response。

須知：ImageResponse 滿足此返回型別。

配置匯出

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

選項型別
altstring
size{ width: number; height: number }
contentTypestring - 圖片 MIME 型別

alt

opengraph-image.tsx | twitter-image.tsx
export const alt = 'My images alt text'
 
export default function Image() {}
<head> 輸出
<meta property="og:image:alt" content="My images alt text" />

size

opengraph-image.tsx | twitter-image.tsx
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

opengraph-image.tsx | twitter-image.tsx
export const contentType = 'image/png'
 
export default function Image() {}
<head> 輸出
<meta property="og:image:type" content="image/png" />

路由段配置

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

示例

使用外部資料

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

須知：預設情況下，此生成的圖片將靜態最佳化。您可以配置單個 fetch options 或路由段選項來更改此行為。

app/posts/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
 
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'
 
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await fetch(`https://.../posts/${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 執行時從檔案系統中獲取本地圖片並將其作為 base64 字串或 ArrayBuffer 傳遞給 <img> 的 src 屬性。將本地資產相對於專案根目錄放置，而不是示例原始檔。

app/opengraph-image.tsx
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'), 'base64')
  const logoSrc = `data:image/png;base64,${logoData}`
 
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

將 ArrayBuffer 傳遞給 <img> 元素的 src 屬性不屬於 HTML 規範的一部分。next/og 使用的渲染引擎支援它，但由於 TypeScript 定義遵循規範，您需要使用 @ts-expect-error 指令或類似指令來使用此功能。

app/opengraph-image.tsx
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',
        }}
      >
        {/* @ts-expect-error Satori accepts ArrayBuffer/typed arrays for <img src> at runtime */}
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

版本歷史

版本更改
v16.0.0params 現在是一個解析為物件的 Promise
v13.3.0引入了 opengraph-image 和 twitter-image。