NNext.js 中文网 GitHub

next/experimental/image-optimizer-transform

experimental

next/experimental/image-optimizer-transform 模块的 API 参考,该模块是 Next.js Image Optimization 背后的独立管道,基于 sharp 实现图片缩放和格式转换。

next/experimental/image-optimizer-transform 模块将 Next.js Image Optimization 的转换步骤暴露为一个依赖较少的独立 Node.js 模块,使图片缩放和格式转换(由 sharp 提供支持)可以在主服务器进程之外运行。

optimize.ts
import { imageOptimizerTransform } from 'next/experimental/image-optimizer-transform'

const result = await imageOptimizerTransform(
  {
    buffer: upstreamBuffer, // 源图片的 Buffer
    contentType: null,
    cacheControl: 'public, max-age=120',
    etag: 'source-etag',
  },
  { href: '/me.png', width: 64, quality: 75, mimeType: 'image/webp' },
  { minimumCacheTTL: 60 }
)
// result.contentType === 'image/webp'
optimize.js
import { imageOptimizerTransform } from 'next/experimental/image-optimizer-transform'

const result = await imageOptimizerTransform(
  {
    buffer: upstreamBuffer, // 源图片的 Buffer
    contentType: null,
    cacheControl: 'public, max-age=120',
    etag: 'source-etag',
  },
  { href: '/me.png', width: 64, quality: 75, mimeType: 'image/webp' },
  { minimumCacheTTL: 60 }
)
// result.contentType === 'image/webp'

参考#

imageOptimizerTransform#

ts
async function imageOptimizerTransform(
  imageUpstream: ImageUpstream,
  paramsResult: ImageOptimizerTransformParams,
  opts?: ImageOptimizerTransformOptions
): Promise<ImageOptimizerResult>

验证上游图片,使用 sharp 进行优化,并返回带有缓存元数据的结果。

imageUpstream#

字段类型描述
bufferBuffer源图片的字节数据。
contentType`string \null \
cacheControl`string \null \
etagstring上游的 ETag。作为 upstreamEtag 返回,当跳过优化时作为 etag 返回。

paramsResult#

字段类型描述
hrefstring图片的源 URL。用于日志和错误消息。
widthnumber目标宽度,单位为像素。
qualitynumber目标质量,1 到 100 之间的整数。
mimeTypestring请求的输出 MIME 类型。空字符串表示无偏好。

opts#

所有字段均为可选。

字段类型默认值描述
dangerouslyAllowSVGbooleanfalse允许 SVG 源。当为 false 时,SVG 源会抛出 ImageError。
minimumCacheTTLnumber0结果的 maxAge 最小值,单位为秒。
concurrency`number \null`undefined
operationCache`boolean \null`undefined
maxInputPixelsnumberundefined作为 limitInputPixels 传给 sharp。省略时使用 sharp 的默认值 268402689。
sequentialRead`boolean \null`undefined
timeoutInSecondsnumber7单张图片的处理超时时间。
mozjpegbooleantrue使用 mozjpeg 编码 JPEG 输出。
loggerobjectundefined一个包含 error(...args) 和 warnOnce(message) 的日志记录器。省略时不记录日志。

这些选项对应于 next.config.js 中的 images 和 experimental.imgOpt* 选项,但默认值不同。例如,Next.js 将 images.minimumCacheTTL 默认设置为 14400。

返回值#

Promise<ImageOptimizerResult>,包含以下字段:

字段类型描述
bufferBuffer优化后的图片,或在跳过优化或优化失败时的上游图片。
contentTypestringbuffer 的 MIME 类型。
maxAgenumber缓存生存时间,单位为秒。
etagstring返回 Buffer 的 ETag。
upstreamEtagstring上游图片的 ETag。
optimizedboolean当 buffer 由 sharp 生成时为 true,当返回上游图片时为 false。
errorunknown仅在优化失败且改为返回上游图片时存在。

该函数按顺序执行以下步骤:

  1. 将 maxAge 计算为 opts.minimumCacheTTL 与上游 Cache-Control 中 s-maxage 或 max-age 指令的较大者。
  2. 根据 imageUpstream.buffer 的魔数检测内容类型。
  3. 当 Buffer 不是可识别的图片,或图片为 SVG 且 opts.dangerouslyAllowSVG 为 false 时,抛出 statusCode 为 400 的 ImageError。
  4. 对动画 WebP、PNG 和 GIF 源不做优化直接返回,并调用 logger.warnOnce。
  5. 对 SVG、ICO、ICNS、BMP、JXL 和 HEIC 源不做修改直接返回。
  6. 选择输出类型:非空时使用 paramsResult.mimeType;对于 WebP 或 AVIF 源,当未请求类型时使用 image/jpeg;否则使用检测到的源类型。
  7. 使用与 sharp 相关的 opts 值,通过 sharp 对图片进行缩放和重新编码。输出会根据源图片的 EXIF 方向自动旋转。
  8. 失败时,返回上游 Buffer 和内容类型,maxAge 设为 opts.minimumCacheTTL,捕获到的值放在 result.error 上。失败不会抛出异常。

getMaxAge#

ts
function getMaxAge(cacheControl: string | null | undefined): number

解析 Cache-Control 标头值,以整数秒数形式返回 s-maxage 指令;当 s-maxage 不存在时返回 max-age 指令。当两个指令都不存在或其值不是数字时返回 0。这与图片优化器在计算 maxAge 时对上游响应采用的解析方式相同。

ts
const maxAge = getMaxAge('public, max-age=120') // 120

getSharp#

ts
function getSharp(
  concurrency: number | null | undefined,
  operationCache: boolean | null | undefined
): typeof import('sharp').default

加载 sharp 模块一次,应用配置,并返回记忆化的实例。

参数类型描述
concurrency`number \null \
operationCache`boolean \null \

首次加载时,getSharp 将 libvips 图片加载器限制为 HEIF (AVIF)、JPEG、GIF、PNG、SVG、TIFF 和 WebP。如果未安装 sharp,它会抛出错误,建议运行 npm install --cpu=wasm32 sharp。

ImageError#

ts
class ImageError extends Error {
  statusCode: number
  constructor(statusCode: number, message: string)
}

imageOptimizerTransform 针对无效输入抛出的错误类型。当 statusCode 为 400 或更高时会保留该值。任何更低的值都会被替换为 500。

小知识#

  • sharp 是必需的,并在首次调用 getSharp 或 imageOptimizerTransform 优化第一张图片时延迟加载。之后会复用同一实例。
  • 该模块有意只引入很少的依赖,以便在单独的进程(例如 worker 或子进程)中快速加载。其文件位置和导出是稳定的公开契约。
  • imageUpstream 的 contentType 字段不用于检测。内容类型是从 Buffer 的前几个字节检测出来的。
  • 优化失败不会抛出异常。imageOptimizerTransform 会返回上游 Buffer,并在结果上设置 error。
  • 动画 WebP、PNG 和 GIF 图片不做优化直接返回。SVG、ICO、ICNS、BMP、JXL 和 HEIC 图片始终不做优化直接透传。

示例#

优化获取到的图片#

获取上游图片并将其转换为 WebP,使用响应标头作为上游元数据。

optimize.ts
import { imageOptimizerTransform } from 'next/experimental/image-optimizer-transform'

const logger = {
  error: (...args: unknown[]) => console.error(...args),
  warnOnce: (message: string) => console.warn(message),
}

const upstream = await fetch('https://example.com/me.png')

const result = await imageOptimizerTransform(
  {
    buffer: Buffer.from(await upstream.arrayBuffer()),
    contentType: upstream.headers.get('content-type'),
    cacheControl: upstream.headers.get('cache-control'),
    etag: upstream.headers.get('etag') ?? 'unknown',
  },
  {
    href: 'https://example.com/me.png',
    width: 64,
    quality: 75,
    mimeType: 'image/webp',
  },
  { minimumCacheTTL: 60, timeoutInSeconds: 10, logger }
)

if (result.error) {
  // 优化失败。result.buffer 包含上游图片。
}
optimize.js
import { imageOptimizerTransform } from 'next/experimental/image-optimizer-transform'

const logger = {
  error: (...args) => console.error(...args),
  warnOnce: (message) => console.warn(message),
}

const upstream = await fetch('https://example.com/me.png')

const result = await imageOptimizerTransform(
  {
    buffer: Buffer.from(await upstream.arrayBuffer()),
    contentType: upstream.headers.get('content-type'),
    cacheControl: upstream.headers.get('cache-control'),
    etag: upstream.headers.get('etag') ?? 'unknown',
  },
  {
    href: 'https://example.com/me.png',
    width: 64,
    quality: 75,
    mimeType: 'image/webp',
  },
  { minimumCacheTTL: 60, timeoutInSeconds: 10, logger }
)

if (result.error) {
  // 优化失败。result.buffer 包含上游图片。
}

使用 getSharp 配置 sharp#

使用 getSharp 加载 sharp,其加载器限制和并发限制与 Next.js 图片优化器相同。

metadata.ts
import { getSharp } from 'next/experimental/image-optimizer-transform'

const sharp = getSharp(1, false)
const metadata = await sharp(buffer).metadata()
metadata.js
import { getSharp } from 'next/experimental/image-optimizer-transform'

const sharp = getSharp(1, false)
const metadata = await sharp(buffer).metadata()
Next.js 中文网