输出选项

toFile

toFile(fileOut, [callback]) ⇒ Promise.<Object>

将输出图像数据写入文件。

如果未选择明确的输出格式，则将根据扩展名推断格式，支持 JPEG、PNG、WebP、AVIF、TIFF、GIF、DZI 以及 libvips 的 V 格式。请注意，仅支持为缓冲区输出提供原始像素数据。

默认情况下，所有元数据将被移除，包括基于 EXIF 的方向。有关此方面的控制，请参见 withMetadata。

调用者负责确保目录结构和权限存在。

当未提供 callback 时，将返回一个 Promise。

返回: Promise.<Object> - 未提供回调时
抛出:

• Error 无效参数

参数	类型	描述
fileOut	string	写入图像数据的路径。
[callback]	function	完成时调用，传递两个参数 (err, info)。info 包含输出图像的 format、size（字节）、width、height、channels 和 premultiplied（指示是否使用了预乘）。当使用裁剪策略时，还包含 cropOffsetLeft 和 cropOffsetTop。使用注意裁剪策略时，还包含 attentionX 和 attentionY，表示裁剪区域的焦点。动画输出还将包含 pageHeight 和 pages。如果图像是从文本创建的，也可能包含 textAutofitDpi（字体渲染时的 DPI）。

示例

sharp(input)
  .toFile('output.png', (err, info) => { ... });

示例

sharp(input)
  .toFile('output.png')
  .then(info => { ... })
  .catch(err => { ... });

toBuffer

toBuffer([options], [callback]) ⇒ Promise.<Buffer>

将输出写入 Buffer。支持 JPEG、PNG、WebP、AVIF、TIFF、GIF 和原始像素数据输出。

使用 toFormat 或其他格式特定函数，如 jpeg、png 等来设置输出格式。

如果未设置明确的格式，则输出格式将与输入图像匹配，除非输入为 SVG，则输出将为 PNG。

默认情况下，所有元数据将被移除，包括基于 EXIF 的方向。有关此方面的控制，请参见 withMetadata。

callback（如果存在）接收三个参数 (err, data, info)，其中：

• err 是一个错误（如果有）。
• data 是输出图像数据。
• info 包含输出图像的 format、size（字节）、width、height、channels 和 premultiplied（指示是否使用了预乘）。当使用裁剪策略时，还包含 cropOffsetLeft 和 cropOffsetTop。动画输出还将包含 pageHeight 和 pages。如果图像是从文本创建的，也可能包含 textAutofitDpi（字体渲染时的 DPI）。

当未提供 callback 时，将返回一个 Promise。

返回: Promise.<Buffer> - 未提供回调时

参数	类型	描述
[options]	Object
[options.resolveWithObject]	boolean	用包含 data 和 info 属性的对象解析 Promise，而不是仅用 data。
[callback]	function

示例

sharp(input)
  .toBuffer((err, data, info) => { ... });

示例

sharp(input)
  .toBuffer()
  .then(data => { ... })
  .catch(err => { ... });

示例

sharp(input)
  .png()
  .toBuffer({ resolveWithObject: true })
  .then(({ data, info }) => { ... })
  .catch(err => { ... });

示例

const { data, info } = await sharp('my-image.jpg')
  // 输出原始像素
  .raw()
  .toBuffer({ resolveWithObject: true });

// 创建一种更安全的方式来处理原始像素数据
// 这不会复制数据，而是会改变 `data` 的底层 ArrayBuffer
// 因此 `data` 和 `pixelArray` 指向相同的内存位置
const pixelArray = new Uint8ClampedArray(data.buffer);

// 当你完成更改 pixelArray 后，sharp 将 `pixelArray` 作为输入
const { width, height, channels } = info;
await sharp(pixelArray, { raw: { width, height, channels } })
  .toFile('my-changed-image.jpg');

keepExif

keepExif() ⇒ Sharp

在输出图像中保留输入图像的所有 EXIF 元数据。

TIFF 输出不支持 EXIF 元数据。

自: 0.33.0
示例

const outputWithExif = await sharp(inputWithExif)
  .keepExif()
  .toBuffer();

withExif

withExif(exif) ⇒ Sharp

在输出图像中设置 EXIF 元数据，忽略输入图像中的任何 EXIF。

抛出:

• Error 无效参数

自: 0.33.0

参数	类型	描述
exif	Object.<string, Object.<string, string>>	按 IFD0、IFD1 等键入的对象，键值对写入为 EXIF 数据。

示例

const dataWithExif = await sharp(input)
  .withExif({
    IFD0: {
      Copyright: '国家美术馆'
    },
    IFD3: {
      GPSLatitudeRef: 'N',
      GPSLatitude: '51/1 30/1 3230/100',
      GPSLongitudeRef: 'W',
      GPSLongitude: '0/1 7/1 4366/100'
    }
  })
  .toBuffer();

withExifMerge

withExifMerge(exif) ⇒ Sharp

在输出图像中更新输入图像的 EXIF 元数据。

抛出:

• Error 无效参数

自: 0.33.0

参数	类型	描述
exif	Object.<string, Object.<string, string>>	按 IFD0、IFD1 等键入的对象，键值对写入为 EXIF 数据。

示例

const dataWithMergedExif = await sharp(inputWithExif)
  .withExifMerge({
    IFD0: {
      Copyright: '国家美术馆'
    }
  })
  .toBuffer();

keepIccProfile

keepIccProfile() ⇒ Sharp

在输出图像中保留输入图像的 ICC 配置文件。

如有必要，将尝试将输出颜色空间转换以匹配该配置文件。

自: 0.33.0
示例

const outputWithIccProfile = await sharp(inputWithIccProfile)
  .keepIccProfile()
  .toBuffer();

withIccProfile

withIccProfile(icc, [options]) ⇒ Sharp

使用 ICC 配置文件进行转换并附加到输出图像。

这可以是绝对文件系统路径或内置配置文件名称（srgb、p3、cmyk）。

抛出:

• Error 无效参数

自: 0.33.0

参数	类型	默认	描述
icc	string		输出 ICC 配置文件的绝对文件系统路径或内置配置文件名称（srgb、p3、cmyk）。
[options]	Object
[options.attach]	number	true	是否将 ICC 配置文件包含在输出图像的元数据中？

示例

const outputWithP3 = await sharp(input)
  .withIccProfile('p3')
  .toBuffer();

keepMetadata

keepMetadata() ⇒ Sharp

在输出图像中保留输入图像的所有元数据（EXIF、ICC、XMP、IPTC）。

当未使用 keepMetadata 时，默认行为是转换为设备独立的 sRGB 颜色空间并剥离所有元数据，包括移除任何 ICC 配置文件。

自: 0.33.0
示例

const outputWithMetadata = await sharp(inputWithMetadata)
  .keepMetadata()
  .toBuffer();

withMetadata

withMetadata([options]) ⇒ Sharp

在输出图像中保留输入图像的大多数元数据（EXIF、XMP、IPTC）。

如果适用，这还将转换并添加一个适于网络的 sRGB ICC 配置文件。

允许设置或更新方向和密度。

抛出:

• Error 无效参数

参数	类型	描述
[options]	Object
[options.orientation]	number	用于更新 EXIF Orientation 标签，整数在 1 和 8 之间。
[options.density]	number	每英寸的像素数（DPI）。

示例

const outputSrgbWithMetadata = await sharp(inputRgbWithMetadata)
  .withMetadata()
  .toBuffer();

示例

// 将输出元数据设置为 96 DPI
const data = await sharp(input)
  .withMetadata({ density: 96 })
  .toBuffer();

toFormat

toFormat(format, options) ⇒ Sharp

强制输出为给定格式。

抛出:

• Error 不支持的格式或选项

参数	类型	描述
format	string | Object	作为字符串或带有 ‘id’ 属性的对象
options	Object	输出选项

示例

// 将任何输入转换为 PNG 输出
const data = await sharp(input)
  .toFormat('png')
  .toBuffer();

jpeg

jpeg([options]) ⇒ Sharp

使用这些 JPEG 选项设置输出图像。

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.progressive]	boolean	false	使用渐进（交错）扫描
[options.chromaSubsampling]	string	“‘4:2:0‘“	设置为 ‘4:4:4’ 以防止色度子采样，否则默认使用 ‘4:2:0’ 色度子采样
[options.optimiseCoding]	boolean	true	优化哈夫曼编码表
[options.optimizeCoding]	boolean	true	优化哈夫曼编码表的另一种拼写
[options.mozjpeg]	boolean	false	使用 mozjpeg 默认值，相当于 { trellisQuantisation: true, overshootDeringing: true, optimiseScans: true, quantisationTable: 3 }
[options.trellisQuantisation]	boolean	false	应用 trellis 量化
[options.overshootDeringing]	boolean	false	应用过冲去锯齿
[options.optimiseScans]	boolean	false	优化渐进扫描，强制渐进
[options.optimizeScans]	boolean	false	优化渐进扫描的另一种拼写
[options.quantisationTable]	number	0	要使用的量化表，整数 0-8
[options.quantizationTable]	number	0	量化表的另一种拼写
[options.force]	boolean	true	强制 JPEG 输出，否则尝试使用输入格式

示例

// 将任何输入转换为非常高质量的 JPEG 输出
const data = await sharp(input)
  .jpeg({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

示例

// 使用 mozjpeg 减小输出 JPEG 文件大小（较慢）
const data = await sharp(input)
  .jpeg({ mozjpeg: true })
  .toBuffer();

png

png([options]) ⇒ Sharp

使用这些 PNG 选项设置输出图像。

默认情况下，PNG 输出为每像素 8 位的全彩色。

1、2 或 4 位每像素的索引 PNG 输入转换为 8 位每像素。 设置 palette 为 true 以获取较慢、索引的 PNG 输出。

对于 16 位每像素输出，通过 toColourspace 转换为 rgb16。

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object
[options.progressive]	boolean	false	使用渐进（交错）扫描
[options.compressionLevel]	number	6	zlib 压缩级别，0（最快、最大）到 9（最慢、最小）
[options.adaptiveFiltering]	boolean	false	使用自适应行过滤
[options.palette]	boolean	false	量化为支持 alpha 透明的调色板图像
[options.quality]	number	100	使用实现给定质量所需的最低颜色数，设置 palette 为 true
[options.effort]	number	7	CPU 努力程度，在 1（最快）和 10（最慢）之间，设置 palette 为 true
[options.colours]	number	256	最大调色板条目数，设置 palette 为 true
[options.colors]	number	256	options.colours 的另一种拼写，设置 palette 为 true
[options.dither]	number	1.0	Floyd-Steinberg 错误扩散的水平，设置 palette 为 true
[options.force]	boolean	true	强制 PNG 输出，否则尝试使用输入格式

示例

// 将任何输入转换为全彩色 PNG 输出
const data = await sharp(input)
  .png()
  .toBuffer();

示例

// 将任何输入转换为索引 PNG 输出（较慢）
const data = await sharp(input)
  .png({ palette: true })
  .toBuffer();

示例

// 输出 16 位每像素 RGB(A)
const data = await sharp(input)
 .toColourspace('rgb16')
 .png()
 .toBuffer();

webp

webp([options]) ⇒ Sharp

使用这些 WebP 选项设置输出图像。

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.alphaQuality]	number	100	alpha 层质量，整数 0-100
[options.lossless]	boolean	false	使用无损压缩模式
[options.nearLossless]	boolean	false	使用近无损压缩模式
[options.smartSubsample]	boolean	false	使用高质量的色度子采样
[options.smartDeblock]	boolean	false	自动调整去块过滤器，可以改善低对比度边缘（较慢）
[options.preset]	string	“‘default‘“	预处理/过滤的命名预设，选项为：default、photo、picture、drawing、icon、text
[options.effort]	number	4	CPU 努力程度，在 0（最快）和 6（最慢）之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		动画帧之间的延迟（以毫秒为单位）
[options.minSize]	boolean	false	防止使用动画关键帧以最小化文件大小（较慢）
[options.mixed]	boolean	false	允许损失和无损动画帧的混合（较慢）
[options.force]	boolean	true	强制 WebP 输出，否则尝试使用输入格式

示例

// 将任何输入转换为无损 WebP 输出
const data = await sharp(input)
  .webp({ lossless: true })
  .toBuffer();

示例

// 优化动画 WebP 的文件大小
const outputWebp = await sharp(inputWebp, { animated: true })
  .webp({ effort: 6 })
  .toBuffer();

gif

gif([options]) ⇒ Sharp

使用这些 GIF 选项为输出图像设置。

调色板中的第一个条目保留用于透明度。

如果可能，将重新使用输入图像的调色板。

抛出:

• Error 无效选项

自: 0.30.0

参数	类型	默认	描述
[options]	Object		输出选项
[options.reuse]	boolean	true	重新使用现有调色板，否则生成新的（较慢）
[options.progressive]	boolean	false	使用渐进（交错）扫描
[options.colours]	number	256	最大调色板条目数，包括透明度，范围在 2 到 256 之间
[options.colors]	number	256	options.colours 的另一种拼写
[options.effort]	number	7	CPU 努力程度，在 1（最快）和 10（最慢）之间
[options.dither]	number	1.0	Floyd-Steinberg 错误扩散的水平，在 0（最少）和 1（最多）之间
[options.interFrameMaxError]	number	0	透明度的最大帧间误差，范围在 0（无损）和 32 之间
[options.interPaletteMaxError]	number	3	调色板重用的最大帧间误差，范围在 0 到 256 之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		动画帧之间的延迟（以毫秒为单位）
[options.force]	boolean	true	强制 GIF 输出，否则尝试使用输入格式

示例

// 将 PNG 转换为 GIF
await sharp(pngBuffer)
  .gif()
  .toBuffer();

示例

// 将动画 WebP 转换为动画 GIF
await sharp('animated.webp', { animated: true })
  .toFile('animated.gif');

示例

// 创建一个 128x128 像素、裁剪的、非抖动的动画缩略图
const out = await sharp('in.gif', { animated: true })
  .resize({ width: 128, height: 128 })
  .gif({ dither: 0 })
  .toBuffer();

示例

// 动画 GIF 的有损文件大小缩减
await sharp('in.gif', { animated: true })
  .gif({ interFrameMaxError: 8 })
  .toFile('optim.gif');

jp2

jp2([options]) ⇒ Sharp

使用这些 JP2 选项设置输出图像。

需要使用 OpenJPEG 编译的 libvips。 预构建的二进制文件不包括此项 - 请参阅 安装自定义 libvips。

抛出:

• Error 无效选项

自: 0.29.1

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.lossless]	boolean	false	使用无损压缩模式
[options.tileWidth]	number	512	水平瓦片大小
[options.tileHeight]	number	512	垂直瓦片大小
[options.chromaSubsampling]	string	“‘4:4:4‘“	设置为 ‘4:2:0’ 以使用色度子采样

示例

// 将任何输入转换为无损 JP2 输出
const data = await sharp(input)
  .jp2({ lossless: true })
  .toBuffer();

示例

// 将任何输入转换为非常高质量 JP2 输出
const data = await sharp(input)
  .jp2({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

tiff

tiff([options]) ⇒ Sharp

使用这些 TIFF 选项设置输出图像。

通过 withMetadata 可以以每英寸像素设置 density，而不是提供 xres 和 yres 以每毫米像素。

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.force]	boolean	true	强制 TIFF 输出，否则尝试使用输入格式
[options.compression]	string	“‘jpeg‘“	压缩选项：none、jpeg、deflate、packbits、ccittfax4、lzw、webp、zstd、jp2k
[options.predictor]	string	“‘horizontal‘“	压缩预测选项：none、horizontal、float
[options.pyramid]	boolean	false	写入图像金字塔
[options.tile]	boolean	false	写入切片 TIFF
[options.tileWidth]	number	256	水平瓦片大小
[options.tileHeight]	number	256	垂直瓦片大小
[options.xres]	number	1.0	每毫米像素的水平分辨率
[options.yres]	number	1.0	每毫米像素的垂直分辨率
[options.resolutionUnit]	string	“‘inch‘“	分辨率单位选项：inch、cm
[options.bitdepth]	number	8	将位深度减少到 1、2 或 4 位
[options.miniswhite]	boolean	false	以白色小图像表示 1 位图像

示例

// 将 SVG 输入转换为 LZW 压缩、每像素 1 位 TIFF 输出
sharp('input.svg')
  .tiff({
    compression: 'lzw',
    bitdepth: 1
  })
  .toFile('1-bpp-output.tiff')
  .then(info => { ... });

avif

avif([options]) ⇒ Sharp

使用这些 AVIF 选项设置输出图像。

不支持 AVIF 图像序列。 预构建的二进制文件仅支持 8 位深度。

抛出:

• Error 无效选项

自: 0.27.0

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	50	质量，整数 1-100
[options.lossless]	boolean	false	使用无损压缩
[options.effort]	number	4	CPU 努力程度，在 0（最快）和 9（最慢）之间
[options.chromaSubsampling]	string	“‘4:4:4‘“	设置为 ‘4:2:0’ 以使用色度子采样
[options.bitdepth]	number	8	将位深度设置为 8、10 或 12 位

示例

const data = await sharp(input)
  .avif({ effort: 2 })
  .toBuffer();

示例

const data = await sharp(input)
  .avif({ lossless: true })
  .toBuffer();

heif

heif(options) ⇒ Sharp

使用这些 HEIF 选项设置输出图像。

对使用 hevc 压缩的受专利保护的 HEIC 图像的支持需要使用全局安装的 libvips 编译，并支持 libheif、libde265 和 x265。

抛出:

• Error 无效选项

自: 0.23.0

参数	类型	默认	描述
options	Object		输出选项
options.compression	string		压缩格式：av1，hevc
[options.quality]	number	50	质量，整数 1-100
[options.lossless]	boolean	false	使用无损压缩
[options.effort]	number	4	CPU 努力程度，在 0（最快）和 9（最慢）之间
[options.chromaSubsampling]	string	“‘4:4:4‘“	设置为 ‘4:2:0’ 以使用色度子采样
[options.bitdepth]	number	8	将位深度设置为 8、10 或 12 位

示例

const data = await sharp(input)
  .heif({ compression: 'hevc' })
  .toBuffer();

jxl

jxl([options]) ⇒ Sharp

使用这些 JPEG-XL (JXL) 选项设置输出图像。

此功能为实验性，请勿在生产系统中使用。

需要支持 libjxl 的 libvips 编译。 预构建的二进制文件不包括此项 - 请参阅 安装自定义 libvips。

抛出:

• Error 无效选项

自: 0.31.3

参数	类型	默认	描述
[options]	Object		输出选项
[options.distance]	number	1.0	最大编码错误，范围在 0（最高质量）到 15（最低质量）之间
[options.quality]	number		根据 JPEG 类似质量计算 distance，范围在 1 到 100 之间，如果指定了则覆盖距离
[options.decodingTier]	number	0	目标解码速度层，范围在 0（最高质量）到 4（最低质量）之间
[options.lossless]	boolean	false	使用无损压缩
[options.effort]	number	7	CPU 努力程度，在 1（最快）和 9（最慢）之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		动画帧之间的延迟（以毫秒为单位）

raw

raw([options]) ⇒ Sharp

强制输出为原始的、无压缩的像素数据。 像素顺序为从左到右、从上到下，不带填充。 通道顺序将是 RGB 或 RGBA，适用于非灰度颜色空间。

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object		输出选项
[options.depth]	string	“‘uchar‘“	位深度，值之一：char、uchar（默认）、short、ushort、int、uint、float、complex、double、dpcomplex

示例

// 从 JPEG 输入提取原始的无符号 8 位 RGB 像素数据
const { data, info } = await sharp('input.jpg')
  .raw()
  .toBuffer({ resolveWithObject: true });

示例

// 从 PNG 输入提取 alpha 通道作为原始的无符号 16 位像素数据
const data = await sharp('input.png')
  .ensureAlpha()
  .extractChannel(3)
  .toColourspace('b-w')
  .raw({ depth: 'ushort' })
  .toBuffer();

tile

tile([options]) ⇒ Sharp

使用基于瓦片的深度缩放（图像金字塔）输出。

通过 toFormat、jpeg、png 或 webp 函数设置瓦片图像的格式和选项。 使用 .zip 或 .szi 文件扩展名与 toFile 一起写入压缩归档文件格式。

当输出为缓冲区或流时，容器将被设置为 zip，否则默认为 fs。

抛出:

• Error 无效参数

参数	类型	默认	描述
[options]	Object
[options.size]	number	256	瓦片大小（以像素为单位），值范围在 1 到 8192 之间。
[options.overlap]	number	0	瓦片重叠（以像素为单位），值范围在 0 到 8192 之间。
[options.angle]	number	0	瓦片的旋转角度，必须是 90 的倍数。
[options.background]	string | Object	”{r: 255, g: 255, b: 255, alpha: 1}“	背景颜色，由 color 模块解析，默认为无透明度的白色。
[options.depth]	string		要制作金字塔的深度，可能的值为 onepixel、onetile 或 one，默认基于布局。
[options.skipBlanks]	number	-1	跳过瓦片生成的阈值。范围为 0-255（8 位图像），0-65535（16 位图像）。默认值为 google 布局的 5，否则为 -1（无跳过）。
[options.container]	string	“‘fs‘“	瓦片容器，值为 fs（文件系统）或 zip（压缩文件）。
[options.layout]	string	“‘dz‘“	文件系统布局，可能的值为 dz、iiif、iiif3、zoomify 或 google。
[options.centre]	boolean	false	在瓦片中居中图像。
[options.center]	boolean	false	centre 的另一种拼写。
[options.id]	string	“‘https://example.com/iiif'“	当 layout 为 iiif/iiif3 时，设置 info.json 的 @id/id 属性
[options.basename]	string		当容器为 zip 时，zip 文件中的目录名称。

示例

sharp('input.tiff')
  .png()
  .tile({
    size: 512
  })
  .toFile('output.dz', function(err, info) {
    // output.dzi 是 Deep Zoom XML 定义
    // output_files 包含按缩放级别分组的 512x512 瓦片
  });

示例

const zipFileWithTiles = await sharp(input)
  .tile({ basename: "tiles" })
  .toBuffer();

示例

const iiififier = sharp().tile({ layout: "iiif" });
readableStream
  .pipe(iiififier)
  .pipe(writeableStream);

timeout

timeout(options) ⇒ Sharp

为处理设置超时（以秒为单位）。 使用零值以无限期继续处理，默认行为。

时钟在 libvips 打开输入图像进行处理时开始。 等待 libuv 线程可用的时间不包括在内。

自: 0.29.2

参数	类型	描述
options	Object
options.seconds	number	超时处理后停止的秒数

示例

// 确保处理时间不超过 3 秒
try {
  const data = await sharp(input)
    .blur(1000)
    .timeout({ seconds: 3 })
    .toBuffer();
} catch (err) {
  if (err.message.includes('timeout')) { ... }
}