15 分钟 Quickstart

这一步把旧中文手记中的“读取 → 处理 → 导出”结构整理成一个可对照的四个 binding 任务：把 input.jpg 缩小到不超过 640 × 640，不放大小图，输出质量为 82 的 output.webp。

Bootstrap 状态

四个 binding 都已经通过统一 Runner 执行，并完成格式、尺寸、通道与公开产物检查。参考输出由 govips 生成；sharp 使用不同的 libvips 版本，因此各 binding 编码字节不需要一致。

1. 准备输入

运行示例时，可以将自己的 JPEG 命名为 input.jpg；尺寸和画面不同会产生不同的输出数据。

输入：JPEG1938 × 1292，610,191 bytes

参考输出：WebP640 × 427，36,172 bytes，quality 82

参考输出由 govips v2.19.0 / libvips 8.17.3 实际生成。

2. 选择 binding 并运行

govips · Reference

运行命令

go run . input.jpg output/

完整源码

package main

import (
	"fmt"
	"os"

	"github.com/davidbyttow/govips/v2/vips"
	"github.com/webp-sh/vips-handbook/examples/internal/recipeutil"
)

func main() {
	if err := run(os.Args); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func run(args []string) error {
	if len(args) != 3 {
		return fmt.Errorf("usage: quickstart-thumbnail <input.jpg> <output-directory>")
	}
	inputPath, outputDir := args[1], args[2]
	if err := os.MkdirAll(outputDir, 0o755); err != nil {
		return err
	}

	if err := vips.Startup(nil); err != nil {
		return fmt.Errorf("start libvips: %w", err)
	}
	defer vips.Shutdown()

	image, err := vips.NewThumbnailFromFile(inputPath, 640, 640, vips.InterestingNone)
	if err != nil {
		return fmt.Errorf("create thumbnail: %w", err)
	}
	defer image.Close()

	output, err := recipeutil.ExportWebp(image, outputDir, "output.webp", 82, map[string]any{
		"width": 640, "height": 640, "crop": "none", "withoutEnlargement": true,
	})
	if err != nil {
		return err
	}
	if output.Width > 640 || output.Height > 640 {
		return fmt.Errorf("unexpected thumbnail dimensions: %dx%d", output.Width, output.Height)
	}
	if err := recipeutil.WriteResult(outputDir, "quickstart-thumbnail", inputPath, []recipeutil.Output{output}); err != nil {
		return err
	}

	fmt.Printf("quickstart-thumbnail: %dx%d, %d bytes\n", output.Width, output.Height, output.Size)
	return nil
}

sharp · 已执行，等待像素比较

运行命令

node index.mjs input.jpg output/

完整源码

import { mkdir, writeFile } from 'node:fs/promises';
import path from 'node:path';
import sharp from 'sharp';

const [inputPath, outputDir] = process.argv.slice(2);
if (!inputPath || !outputDir) {
  console.error('Usage: node index.mjs <input.jpg> <output-directory>');
  process.exit(2);
}

try {
  await mkdir(outputDir, { recursive: true });
  const outputPath = path.join(outputDir, 'output.webp');
  const writeResult = await sharp(inputPath)
    .resize(640, 640, { fit: 'inside', withoutEnlargement: true })
    .webp({ quality: 82 })
    .toFile(outputPath);

  if (writeResult.width > 640 || writeResult.height > 640) {
    throw new Error(`Unexpected thumbnail dimensions: ${writeResult.width}x${writeResult.height}`);
  }

  await writeFile(
    path.join(outputDir, 'result.json'),
    `${JSON.stringify({
      recipeId: 'quickstart-thumbnail',
      generator: { sharp: sharp.versions.sharp, libvips: sharp.versions.vips },
      input: path.basename(inputPath),
      outputs: [{
        path: 'output.webp',
        format: writeResult.format,
        width: writeResult.width,
        height: writeResult.height,
        size: writeResult.size,
      }],
    }, null, 2)}\n`,
  );

  console.log(`quickstart-thumbnail: ${writeResult.width}x${writeResult.height}, ${writeResult.size} bytes`);
} catch (error) {
  console.error(error);
  process.exit(1);
}

pyvips · 已执行，等待像素比较

运行命令

python3 main.py input.jpg output/

完整源码

import sys
import json
import os
import pyvips

input_path, output_dir = sys.argv[1], sys.argv[2]
if not input_path or not output_dir:
    print("Usage: python3 main.py <input.jpg> <output-directory>", file=sys.stderr)
    raise SystemExit(2)

os.makedirs(output_dir, exist_ok=True)
output_path = os.path.join(output_dir, "output.webp")

try:
    image = pyvips.Image.thumbnail(input_path, 640, height=640, size="down")
    image.write_to_file(output_path, Q=82)

    if image.width > 640 or image.height > 640:
        raise ValueError(f"Unexpected thumbnail dimensions: {image.width}x{image.height}")

    result_path = os.path.join(output_dir, "result.json")
    with open(result_path, "w") as f:
        json.dump({
            "recipeId": "quickstart-thumbnail",
            "generator": {
                "pyvips": pyvips.__version__,
                "libvips": f"{pyvips.version(0)}.{pyvips.version(1)}.{pyvips.version(2)}",
            },
            "input": os.path.basename(input_path),
            "outputs": [{
                "path": "output.webp",
                "format": "webp",
                "width": image.width,
                "height": image.height,
                "bands": image.bands,
                "hasAlpha": image.hasalpha(),
                "size": os.path.getsize(output_path),
            }],
        }, f, indent=2)
        f.write("\n")

    print(f"quickstart-thumbnail: {image.width}x{image.height}, {os.path.getsize(output_path)} bytes")
except pyvips.Error as error:
    print(error, file=sys.stderr)
    raise SystemExit(1)

vips CLI · 已执行，等待像素比较

运行命令

bash run.sh input.jpg output/

完整源码

#!/usr/bin/env bash
set -euo pipefail

INPUT="$1"
OUTPUT_DIR="$2"

if [ $# -ne 2 ]; then
    echo "Usage: bash run.sh <input.jpg> <output-directory>" >&2
    exit 2
fi

mkdir -p "$OUTPUT_DIR"
OUTPUT_WEBP="$OUTPUT_DIR/output.webp"

vips thumbnail "$INPUT" "$OUTPUT_WEBP[Q=82]" 640 --height 640 --size down

IDATA="$(vipsheader --all "$OUTPUT_WEBP")"
WIDTH="$(echo "$IDATA" | grep '^width:' | awk '{print $2}')"
HEIGHT="$(echo "$IDATA" | grep '^height:' | awk '{print $2}')"
BANDS="$(echo "$IDATA" | grep '^bands:' | awk '{print $2}')"
FILESIZE="$(stat -c%s "$OUTPUT_WEBP")"
LIBVIPS_VER="$(vips --version | sed 's/vips-//')"

if [ "$WIDTH" -gt 640 ] || [ "$HEIGHT" -gt 640 ]; then
    echo "Unexpected thumbnail dimensions: ${WIDTH}x${HEIGHT}" >&2
    exit 1
fi

cat > "$OUTPUT_DIR/result.json" << EOF
{
  "recipeId": "quickstart-thumbnail",
  "generator": {
    "vipsCli": "${LIBVIPS_VER}",
    "libvips": "${LIBVIPS_VER}"
  },
  "input": "$(basename "$INPUT")",
  "outputs": [{
    "path": "output.webp",
    "format": "webp",
    "width": ${WIDTH},
    "height": ${HEIGHT},
    "bands": ${BANDS},
    "hasAlpha": false,
    "size": ${FILESIZE}
  }]
}
EOF

echo "quickstart-thumbnail: ${WIDTH}x${HEIGHT}, ${FILESIZE} bytes"

3. 检查结果

至少确认 output.webp 存在且能被重新读取；宽和高都不超过 640；输入小于目标尺寸时没有被放大；输出格式确实是 WebP 而不是只改了扩展名。

• Format: WEBP
• Dimensions: 640 × 427
• Bands: 3
• Alpha: No
• File size: 36,172 bytes
• Generated with: govips v2.19.0 / libvips 8.17.3

四段代码表达同一个产品目标，但不是逐行等价：govips 和 pyvips 直接调用 thumbnail 能力，sharp 用 resize({ fit: 'inside' }) 表达边界，CLI 则通过操作参数传递保存选项。

下一步

继续阅读构建第一个完整图像 Pipeline，把输入检查、方向归一化、编码和结果验证拆成明确阶段。

来源

• govips 官方仓库
• sharp resize
• pyvips Image API
• libvips CLI