Sharp 中文网

Appearance

API 参考 ​

Sharp 提供了丰富的 API 来处理图像。本页面提供了所有可用方法的详细参考。

构造函数 ​

sharp(input, options?) ​

创建一个新的 Sharp 实例。

javascript
import sharp from 'sharp';

// 从文件创建
const image = sharp('input.jpg');

// 从 Buffer 创建
const image = sharp(buffer);

// 从 Stream 创建
const image = sharp(stream);

// 创建空白图像
const image = sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 1 }
  }
});

输入元数据 ​

metadata() ​

获取图像的元数据信息。

javascript
const metadata = await sharp('input.jpg').metadata();
console.log(metadata);
// {
//   format: 'jpeg',
//   width: 1920,
//   height: 1080,
//   space: 'srgb',
//   channels: 3,
//   depth: 'uchar',
//   density: 72,
//   hasProfile: false,
//   hasAlpha: false
// }

stats() ​

获取图像的统计信息。

javascript
const stats = await sharp('input.jpg').stats();
console.log(stats);
// {
//   isOpaque: true,
//   dominant: { r: 128, g: 128, b: 128 }
// }

输出选项 ​

toFile(filename, callback?) ​

将处理后的图像保存到文件。

javascript
await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

toBuffer(options?, callback?) ​

将处理后的图像输出为 Buffer。

javascript
const buffer = await sharp('input.jpg')
  .resize(300, 200)
  .jpeg()
  .toBuffer();

toFormat(format, options?) ​

设置输出格式。

javascript
// JPEG
await sharp('input.png')
  .jpeg({ quality: 80, progressive: true })
  .toFile('output.jpg');

// PNG
await sharp('input.jpg')
  .png({ compressionLevel: 9, adaptiveFiltering: true })
  .toFile('output.png');

// WebP
await sharp('input.jpg')
  .webp({ quality: 80, effort: 6 })
  .toFile('output.webp');

// AVIF
await sharp('input.jpg')
  .avif({ quality: 80, effort: 4 })
  .toFile('output.avif');

// TIFF
await sharp('input.jpg')
  .tiff({ quality: 80, compression: 'lzw' })
  .toFile('output.tiff');

格式压缩示例 ​

压缩前：384 kb

压缩后：145 kb

javascript
const sharp = require('sharp');

// 原始图片路径
const inputPath = 'mm-before.jpg';
// 压缩后图片的输出路径
const outputPath = 'mm-after.jpg';

// 设置压缩选项，这里我们使用mozjpeg的优化功能
const options = {
  compression: 75 // 设置JPEG的压缩质量，范围从0到100
};

// 使用sharp处理图片
sharp(inputPath)
  .resize(null, null, { // 调整图片大小，这里不改变原始尺寸
    withoutEnlargement: true
  })
  .toFormat('jpeg', options) // 转换为JPEG格式，并应用压缩选项
  .toFile(outputPath, (err, info) => {
    if (err) {
      console.error(err);
    } else {
      console.log(`图片压缩成功，保存为: ${outputPath}`);
    }
  });

图像调整 ​

resize(width?, height?, options?) ​

调整图像大小。

javascript
// 基本调整
await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

// 保持宽高比
await sharp('input.jpg')
  .resize(300, null)
  .toFile('output.jpg');

// 使用适配模式
await sharp('input.jpg')
  .resize(300, 200, {
    fit: 'cover',        // 裁剪以适应
    position: 'center',  // 居中裁剪
    background: { r: 255, g: 255, b: 255, alpha: 1 }
  })
  .toFile('output.jpg');

// 使用内核
await sharp('input.jpg')
  .resize(300, 200, {
    kernel: sharp.kernel.lanczos3
  })
  .toFile('output.jpg');

extract(region) ​

裁剪图像区域。

javascript
await sharp('input.jpg')
  .extract({ left: 100, top: 100, width: 200, height: 200 })
  .toFile('cropped.jpg');

trim(threshold?) ​

自动裁剪透明或白色边缘。

javascript
await sharp('input.png')
  .trim()
  .toFile('trimmed.png');

图像操作 ​

rotate(angle, options?) ​

旋转图像。

javascript
// 旋转 90 度
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated.jpg');

// 旋转并填充背景
await sharp('input.jpg')
  .rotate(45, { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('rotated.jpg');

flip(flip?) ​

垂直翻转图像。

javascript
await sharp('input.jpg')
  .flip()
  .toFile('flipped.jpg');

flop(flop?) ​

水平翻转图像。

javascript
await sharp('input.jpg')
  .flop()
  .toFile('flopped.jpg');

affine(matrix, options?) ​

应用仿射变换。

javascript
await sharp('input.jpg')
  .affine([[1, 0.3], [0, 1]], { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('transformed.jpg');

滤镜效果 ​

blur(sigma?) ​

应用高斯模糊。

javascript
await sharp('input.jpg')
  .blur(5)
  .toFile('blurred.jpg');

sharpen(sigma?, flat?, jagged?) ​

应用锐化滤镜。

javascript
await sharp('input.jpg')
  .sharpen()
  .toFile('sharpened.jpg');

// 自定义锐化参数
await sharp('input.jpg')
  .sharpen(1, 1, 2)
  .toFile('sharpened.jpg');

median(size?) ​

应用中值滤镜。

javascript
await sharp('input.jpg')
  .median(3)
  .toFile('median.jpg');

flatten(options?) ​

合并透明通道。

javascript
await sharp('input.png')
  .flatten({ background: { r: 255, g: 255, b: 255 } })
  .toFile('flattened.jpg');

色彩操作 ​

grayscale(grayscale?) ​

转换为灰度图像。

javascript
await sharp('input.jpg')
  .grayscale()
  .toFile('grayscale.jpg');

negate(negate?) ​

负片效果。

javascript
await sharp('input.jpg')
  .negate()
  .toFile('negated.jpg');

modulate(options?) ​

调整亮度、饱和度和色调。

javascript
await sharp('input.jpg')
  .modulate({
    brightness: 1.2,    // 亮度
    saturation: 0.8,    // 饱和度
    hue: 90             // 色调
  })
  .toFile('modulated.jpg');

tint(rgb) ​

应用色调。

javascript
await sharp('input.jpg')
  .tint({ r: 255, g: 0, b: 0 })
  .toFile('tinted.jpg');

removeAlpha() ​

移除透明通道。

javascript
await sharp('input.png')
  .removeAlpha()
  .toFile('no-alpha.jpg');

ensureAlpha() ​

确保有透明通道。

javascript
await sharp('input.jpg')
  .ensureAlpha()
  .toFile('with-alpha.png');

通道操作 ​

bandbool(boolean) ​

对通道应用布尔运算。

javascript
await sharp('input.jpg')
  .bandbool('and')
  .toFile('bandbool.jpg');

joinChannel(channels) ​

合并通道。

javascript
await sharp('input.jpg')
  .joinChannel(['red.jpg', 'green.jpg', 'blue.jpg'])
  .toFile('joined.jpg');

extractChannel(channel) ​

提取单个通道。

javascript
await sharp('input.jpg')
  .extractChannel('red')
  .toFile('red-channel.jpg');

全局属性 ​

sharp.versions ​

获取版本信息。

javascript
console.log(sharp.versions);
// {
//   sharp: '0.32.0',
//   vips: '8.14.0'
// }

sharp.format ​

获取支持的格式。

javascript
console.log(sharp.format);
// {
//   jpeg: { id: 'jpeg', ... },
//   png: { id: 'png', ... },
//   webp: { id: 'webp', ... },
//   ...
// }

sharp.kernel ​

获取可用的内核。

javascript
console.log(sharp.kernel);
// {
//   nearest: 'nearest',
//   cubic: 'cubic',
//   mitchell: 'mitchell',
//   lanczos2: 'lanczos2',
//   lanczos3: 'lanczos3'
// }

错误处理 ​

javascript
try {
  await sharp('input.jpg')
    .resize(300, 200)
    .toFile('output.jpg');
} catch (error) {
  console.error('图像处理失败:', error);
}

性能优化 ​

流式处理 ​

javascript
const pipeline = sharp()
  .resize(300, 200)
  .jpeg({ quality: 80 });

fs.createReadStream('large-input.jpg')
  .pipe(pipeline)
  .pipe(fs.createWriteStream('output.jpg'));

并发处理 ​

javascript
const promises = images.map(image => 
  sharp(image)
    .resize(300, 200)
    .jpeg()
    .toBuffer()
);

const results = await Promise.all(promises);

完整示例 ​

javascript
import sharp from 'sharp';

async function processImage() {
  try {
    // 获取元数据
    const metadata = await sharp('input.jpg').metadata();
    console.log('原始图像尺寸:', metadata.width, 'x', metadata.height);

    // 创建多个版本
    const promises = [
      // 缩略图
      sharp('input.jpg')
        .resize(150, 150, { fit: 'cover' })
        .jpeg({ quality: 90 })
        .toFile('thumbnail.jpg'),

      // 中等尺寸
      sharp('input.jpg')
        .resize(800, 600, { fit: 'inside' })
        .webp({ quality: 80 })
        .toFile('medium.webp'),

      // 大尺寸
      sharp('input.jpg')
        .resize(1920, 1080, { fit: 'inside' })
        .jpeg({ quality: 85, progressive: true })
        .toFile('large.jpg'),

      // 灰度版本
      sharp('input.jpg')
        .grayscale()
        .jpeg({ quality: 80 })
        .toFile('grayscale.jpg')
    ];

    await Promise.all(promises);
    console.log('所有图像处理完成！');
  } catch (error) {
    console.error('处理失败:', error);
  }
}

processImage();

下一步 ​

Released under the Apache 2.0 License.

Copyright © 2013-present Lovell Fuller and contributors