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 提供支持)可以在主服务器进程之外运行。
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'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#
async function imageOptimizerTransform(
imageUpstream: ImageUpstream,
paramsResult: ImageOptimizerTransformParams,
opts?: ImageOptimizerTransformOptions
): Promise<ImageOptimizerResult>验证上游图片,使用 sharp 进行优化,并返回带有缓存元数据的结果。
imageUpstream#
| 字段 | 类型 | 描述 |
|---|---|---|
buffer | Buffer | 源图片的字节数据。 |
contentType | `string \ | null \ |
cacheControl | `string \ | null \ |
etag | string | 上游的 ETag。作为 upstreamEtag 返回,当跳过优化时作为 etag 返回。 |
paramsResult#
| 字段 | 类型 | 描述 |
|---|---|---|
href | string | 图片的源 URL。用于日志和错误消息。 |
width | number | 目标宽度,单位为像素。 |
quality | number | 目标质量,1 到 100 之间的整数。 |
mimeType | string | 请求的输出 MIME 类型。空字符串表示无偏好。 |
opts#
所有字段均为可选。
| 字段 | 类型 | 默认值 | 描述 |
|---|---|---|---|
dangerouslyAllowSVG | boolean | false | 允许 SVG 源。当为 false 时,SVG 源会抛出 ImageError。 |
minimumCacheTTL | number | 0 | 结果的 maxAge 最小值,单位为秒。 |
concurrency | `number \ | null` | undefined |
operationCache | `boolean \ | null` | undefined |
maxInputPixels | number | undefined | 作为 limitInputPixels 传给 sharp。省略时使用 sharp 的默认值 268402689。 |
sequentialRead | `boolean \ | null` | undefined |
timeoutInSeconds | number | 7 | 单张图片的处理超时时间。 |
mozjpeg | boolean | true | 使用 mozjpeg 编码 JPEG 输出。 |
logger | object | undefined | 一个包含 error(...args) 和 warnOnce(message) 的日志记录器。省略时不记录日志。 |
这些选项对应于 next.config.js 中的 images 和 experimental.imgOpt* 选项,但默认值不同。例如,Next.js 将 images.minimumCacheTTL 默认设置为 14400。
返回值#
Promise<ImageOptimizerResult>,包含以下字段:
| 字段 | 类型 | 描述 |
|---|---|---|
buffer | Buffer | 优化后的图片,或在跳过优化或优化失败时的上游图片。 |
contentType | string | buffer 的 MIME 类型。 |
maxAge | number | 缓存生存时间,单位为秒。 |
etag | string | 返回 Buffer 的 ETag。 |
upstreamEtag | string | 上游图片的 ETag。 |
optimized | boolean | 当 buffer 由 sharp 生成时为 true,当返回上游图片时为 false。 |
error | unknown | 仅在优化失败且改为返回上游图片时存在。 |
该函数按顺序执行以下步骤:
- 将
maxAge计算为opts.minimumCacheTTL与上游Cache-Control中s-maxage或max-age指令的较大者。 - 根据
imageUpstream.buffer的魔数检测内容类型。 - 当 Buffer 不是可识别的图片,或图片为 SVG 且
opts.dangerouslyAllowSVG为false时,抛出statusCode为 400 的ImageError。 - 对动画 WebP、PNG 和 GIF 源不做优化直接返回,并调用
logger.warnOnce。 - 对 SVG、ICO、ICNS、BMP、JXL 和 HEIC 源不做修改直接返回。
- 选择输出类型:非空时使用
paramsResult.mimeType;对于 WebP 或 AVIF 源,当未请求类型时使用image/jpeg;否则使用检测到的源类型。 - 使用与 sharp 相关的
opts值,通过 sharp 对图片进行缩放和重新编码。输出会根据源图片的 EXIF 方向自动旋转。 - 失败时,返回上游 Buffer 和内容类型,
maxAge设为opts.minimumCacheTTL,捕获到的值放在result.error上。失败不会抛出异常。
getMaxAge#
function getMaxAge(cacheControl: string | null | undefined): number解析 Cache-Control 标头值,以整数秒数形式返回 s-maxage 指令;当 s-maxage 不存在时返回 max-age 指令。当两个指令都不存在或其值不是数字时返回 0。这与图片优化器在计算 maxAge 时对上游响应采用的解析方式相同。
const maxAge = getMaxAge('public, max-age=120') // 120getSharp#
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#
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,使用响应标头作为上游元数据。
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 包含上游图片。
}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 图片优化器相同。
import { getSharp } from 'next/experimental/image-optimizer-transform'
const sharp = getSharp(1, false)
const metadata = await sharp(buffer).metadata()import { getSharp } from 'next/experimental/image-optimizer-transform'
const sharp = getSharp(1, false)
const metadata = await sharp(buffer).metadata()