使用 Sharp 构建图像处理流程

Why Sharp for Image Pipelines

The Sharp Pipeline Mental Model

import sharp from 'sharp';

async function run(): Promise<void> {
  // 1x1 red pixel PNG, base64-encoded
  const pngBase64 =
    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
  const input = Buffer.from(pngBase64, 'base64');

  // Pipeline: queue resize + WebP, then execute with toBuffer()
  const output = await sharp(input)
    .resize(64, 64)
    .webp({ quality: 80 })
    .toBuffer();

  console.log('Output bytes:', output.length);
  console.log('Is WebP:', output.slice(8, 12).toString() === 'WEBP');
}

run().catch((err) => console.error(err));

Reading Metadata Before You Trust It

import sharp, { Metadata } from 'sharp';

const ALLOWED = new Set(['jpeg', 'png', 'webp', 'avif']);

async function validateImage(buffer: Buffer): Promise<Metadata> {
  const meta = await sharp(buffer).metadata();

  if (!meta.format || !ALLOWED.has(meta.format)) {
    throw new Error(`Unsupported image format: ${meta.format ?? 'unknown'}`);
  }
  if (!meta.width || !meta.height) {
    throw new Error('Image has no readable dimensions');
  }
  return meta;
}

// 1x1 red pixel PNG
const png = Buffer.from(
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
  'base64',
);

validateImage(png)
  .then((m) => console.log(`OK: ${m.format} ${m.width}x${m.height}`))
  .catch((e) => console.error(e.message));

Guarding Against Decompression Bombs

import sharp from 'sharp';

const MAX_PIXELS = 24_000_000; // ~24 MP cap

async function safeDecode(buffer: Buffer): Promise<Buffer> {
  const meta = await sharp(buffer).metadata();
  const pixels = (meta.width ?? 0) * (meta.height ?? 0);

  if (pixels > MAX_PIXELS) {
    throw new Error(`Image too large: ${pixels} pixels exceeds ${MAX_PIXELS}`);
  }

  // Hard cap inside libvips as a second line of defence
  return sharp(buffer, { limitInputPixels: MAX_PIXELS })
    .rotate() // auto-orient from EXIF before stripping it
    .toBuffer();
}

safeDecode(Buffer.from('not an image'))
  .then(() => console.log('decoded'))
  .catch((e) => console.error('rejected:', e.message));

Resize Strategies: fit and position

import sharp from 'sharp';

function buildResize(input: Buffer) {
  return sharp(input).resize({
    width: 512,
    height: 512,
    fit: 'cover',
    position: 'attention', // crop toward the most salient region
    withoutEnlargement: true,
  });
}

export { buildResize };

Transcoding to Modern Formats

import sharp from 'sharp';

export type Variant = 'thumb' | 'display';

export function transcode(input: Buffer, variant: Variant): Promise<Buffer> {
  const size = variant === 'thumb' ? 160 : 1280;

  return sharp(input)
    .resize({ width: size, height: size, fit: 'inside', withoutEnlargement: true })
    .webp({
      quality: variant === 'thumb' ? 70 : 82,
      effort: 4, // 0 (fast) .. 6 (slow, smallest)
    })
    .toBuffer();
}

Stripping Metadata and Fixing Orientation

import sharp from 'sharp';

export function normalize(input: Buffer): Promise<Buffer> {
  return sharp(input)
    .rotate() // apply EXIF orientation into the pixels
    .resize({ width: 1080, fit: 'inside', withoutEnlargement: true })
    .keepIccProfile() // preserve color accuracy, drop everything else
    .webp({ quality: 80 })
    .toBuffer(); // EXIF (incl. GPS) is gone from the output
}

Wrapping the Pipeline in a NestJS Service

import { Injectable, BadRequestException } from '@nestjs/common';
import sharp from 'sharp';

const ALLOWED = new Set(['jpeg', 'png', 'webp', 'avif']);
const MAX_PIXELS = 24_000_000;

export interface ProcessedImage {
  thumb: Buffer;
  display: Buffer;
  width: number;
  height: number;
}

@Injectable()
export class ImageProcessingService {
  async process(buffer: Buffer): Promise<ProcessedImage> {
    const meta = await sharp(buffer).metadata();

    if (!meta.format || !ALLOWED.has(meta.format)) {
      throw new BadRequestException('Unsupported image format');
    }
    const pixels = (meta.width ?? 0) * (meta.height ?? 0);
    if (pixels === 0 || pixels > MAX_PIXELS) {
      throw new BadRequestException('Invalid image dimensions');
    }

    const base = () =>
      sharp(buffer, { limitInputPixels: MAX_PIXELS }).rotate();

    const [thumb, display] = await Promise.all([
      base().resize({ width: 160, height: 160, fit: 'cover' }).webp({ quality: 70 }).toBuffer(),
      base().resize({ width: 1280, fit: 'inside', withoutEnlargement: true }).webp({ quality: 82 }).toBuffer(),
    ]);

    return { thumb, display, width: meta.width!, height: meta.height! };
  }
}

Keeping It Background-Safe with a Queue

import { Injectable } from '@nestjs/common';
import { InjectQueue } from '@nestjs/bullmq';
import { Queue } from 'bullmq';

export interface ImageJob {
  assetId: string;
  storageKey: string; // where the raw upload lives
}

@Injectable()
export class ImageUploadService {
  constructor(@InjectQueue('image') private readonly queue: Queue) {}

  async enqueue(job: ImageJob): Promise<void> {
    await this.queue.add('process', job, {
      attempts: 3,
      backoff: { type: 'exponential', delay: 2000 },
      removeOnComplete: true,
    });
  }
}

Streaming Large Files Without Buffering

import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import sharp from 'sharp';

export async function streamResize(
  inputPath: string,
  outputPath: string,
): Promise<void> {
  const transform = sharp()
    .rotate()
    .resize({ width: 1280, fit: 'inside', withoutEnlargement: true })
    .webp({ quality: 82 });

  await pipeline(
    createReadStream(inputPath),
    transform,
    createWriteStream(outputPath),
  );
}

Tuning Concurrency and Caches

import sharp from 'sharp';
import os from 'node:os';

// Call once during bootstrap (e.g. in main.ts before app.listen)
export function configureSharp(): void {
  sharp.concurrency(Math.max(1, os.cpus().length - 1));
  sharp.cache({ memory: 64, files: 0, items: 100 });
  console.log('Sharp concurrency:', sharp.concurrency());
}

Quick Check: Orientation and Privacy

Recap: A Production Image Pipeline