Next.js 中文网

主题

ImageResponse ​

ImageResponse 构造函数允许你使用 JSX 和 CSS 生成动态图片。这对于生成社交媒体图片（例如 Open Graph 图片、Twitter 卡等）非常有用。

¥The ImageResponse constructor allows you to generate dynamic images using JSX and CSS. This is useful for generating social media images such as Open Graph images, Twitter cards, and more.

参考 ​

¥Reference

参数 ​

¥Parameters

以下参数可用于 ImageResponse：

¥The following parameters are available for ImageResponse:

Vercel OG 在线运行 中提供了示例。

¥Examples are available in the Vercel OG Playground.

支持的 HTML 和 CSS 特性 ​

¥Supported HTML and CSS features

ImageResponse 支持常见的 CSS 属性，包括 Flexbox 和绝对定位、自定义字体、文本换行、居中和嵌套图片。

¥ImageResponse supports common CSS properties including flexbox and absolute positioning, custom fonts, text wrapping, centering, and nested images.

请参阅 Satori 的文档 了解受支持的 HTML 和 CSS 功能的列表。

¥Please refer to Satori’s documentation for a list of supported HTML and CSS features.

行为 ​

¥Behavior

  • ImageResponse 使用 @vercel/og、Satori 和 Resvg 将 HTML 和 CSS 转换为 PNG。

    ¥ImageResponse uses @vercel/og, Satori, and Resvg to convert HTML and CSS into PNG.

  • 仅支持 flexbox 和 CSS 属性的子集。高级布局（例如 display: grid）将不起作用。

    ¥Only flexbox and a subset of CSS properties are supported. Advanced layouts (e.g. display: grid) will not work.

  • 最大打包尺寸为 500KB。打包包大小包括 JSX、CSS、字体、图片和任何其他资源。如果超出限制，请考虑减少任何资源的大小或在运行时获取。

    ¥Maximum bundle size of 500KB. The bundle size includes your JSX, CSS, fonts, images, and any other assets. If you exceed the limit, consider reducing the size of any assets or fetching at runtime.

  • 仅支持 ttf、otf 和 woff 字体格式。为了最大化字体解析速度，ttf 或 otf 优于 woff。

    ¥Only ttf, otf, and woff font formats are supported. To maximize the font parsing speed, ttf or otf are preferred over woff.

示例 ​

¥Examples

路由处理程序 ​

¥Route Handlers

ImageResponse 可用于路由处理程序，在请求时动态生成图片。

¥ImageResponse can be used in Route Handlers to generate images dynamically at request time.

基于文件的元数据 ​

¥File-based Metadata

你可以在 opengraph-image.tsx 文件中使用 ImageResponse 在构建时生成 Open Graph 图片，或在请求时动态生成。

¥You can use ImageResponse in a opengraph-image.tsx file to generate Open Graph images at build time or dynamically at request time.

tsx
import { ImageResponse } from 'next/og'

// Image metadata
export const alt = 'My site'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Image generation
export default async function Image() {
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        My site
      </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,
    }
  )
}

自定义字体 ​

¥Custom fonts

你可以通过在选项中提供 fonts 数组，在 ImageResponse 中使用自定义字体。

¥You can use custom fonts in your ImageResponse by providing a fonts array in the options.

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

// Image metadata
export const alt = 'My site'
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 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,
        },
      ],
    }
  )
}

版本历史 ​

¥Version History

版本更改
v14.0.0ImageResponse 从 next/server 移至 next/og
v13.3.0可以从 next/server 导入 ImageResponse。
v13.0.0ImageResponse 通过 @vercel/og 包引入。