跳至內容
檔案慣例詮釋資料檔案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 檔案作為其替代文字。

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 檔案作為其替代文字。

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'
 
export const runtime = 'edge'
 
// 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
  const interSemiBold = fetch(
    new URL('./Inter-SemiBold.ttf', import.meta.url)
  ).then((res) => res.arrayBuffer())
 
  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: await 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" />

屬性 params（選填）

一個包含從根區段到與 opengraph-image 或 twitter-image 位於同一位置的區段的動態路由參數物件。

app/shop/[slug]/opengraph-image.tsx
export default function Image({ params }: { params: { slug: string } }) {
  // ...
}
路由網址params
app/shop/opengraph-image.js/shop未定義
app/shop/[slug]/opengraph-image.js/shop/1{ slug: '1' }
app/shop/[tag]/[item]/opengraph-image.js/shop/1/2{ tag: '1', item: '2' }
app/shop/[...slug]/opengraph-image.js/shop/1/2/shop/1/2

{ slug: ['1', '2'] }

回傳值

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

注意事項：ImageResponse 符合此回傳類型。

設定匯出

您可以選擇性地透過從 opengraph-image 或 twitter-image 路由匯出 alt、size 和 contentType 變數來設定圖片的後設資料。選項
alt類型
size字串
contentType{ width: 數字; height: 數字 }

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 是專門的路由處理器，可以使用與頁面和佈局相同的路由區段設定選項。

範例 使用外部數據

貼心小提醒：預設情況下，產生的圖片會經過靜態最佳化。您可以設定個別的 fetch 選項或路由區段選項來更改此行為。

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: { 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,
    }
  )
}

使用 Edge 執行環境搭配本地資源

此範例使用 Edge 執行環境來擷取檔案系統上的本地圖片，並將其作為 ArrayBuffer 傳遞給 <img> 元素的 src 屬性。本地資源應放置在範例原始檔位置的相對路徑下。

app/opengraph-image.tsx
import { ImageResponse } from 'next/og'
 
export const runtime = 'edge'
 
export default async function Image() {
  const logoSrc = await fetch(new URL('./logo.png', import.meta.url)).then(
    (res) => res.arrayBuffer()
  )
 
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

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

此範例使用 Node.js 執行環境來擷取檔案系統上的本地圖片，並將其作為 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'))
  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。