构建第一个完整图像 Pipeline

一个生产图像 Pipeline 不只是连续调用几个图像方法。它需要在读取像素之前限制输入，在输出之后验证事实，并把 binding 版本、耗时和失败阶段留给日志与监控。

六个阶段

阶段	需要决定什么	最小输出
1. 接收	允许的来源、大小和超时	输入标识与字节数
2. 探测	格式、尺寸、页数、方向、色彩信息	规范化元数据
3. 归一化	EXIF Orientation、Alpha、工作色彩空间	可预测的内部图像
4. 变换	resize/crop 顺序、是否放大、背景策略	目标画布
5. 编码	格式、质量、元数据和 Profile 策略	原始输出文件
6. 验证	格式、尺寸、页数、文件大小与可重读性	验证结果清单

当前 Quickstart 已经跑通其中最小的一条路径：读取项目自有 JPEG，用 govips 生成不放大的 WebP 缩略图，并写出尺寸、格式、文件大小与工具版本清单。

接收与探测1938 × 1292 JPEG，610,191 bytes

变换、编码与验证640 × 427 WebP，36,172 bytes

这组结果证明基础路径可以执行，但尚未实现本页要求的不可信输入限制、方向归一化和失败阶段观测，因此不能当作完整生产 Pipeline。

先探测，再决定

不要仅根据文件扩展名选择 Loader。探测得到的格式、尺寸和页数应与业务限制比较；超限输入要在昂贵的完整解码前尽早拒绝。对于动画和多页输入，还要明确处理全部页面、只取第一页，还是拒绝。

归一化不是固定模板

旧中文手记把读取后得到的 ImageRef 当作后续操作起点，这个思路可以保留，但生产实现还要显式处理：

• EXIF Orientation 是否在裁剪前应用；
• 透明像素在缩放或合成前是否需要 premultiply；
• CMYK 或带 ICC 的输入要转换到哪个目标色彩空间；
• 是否允许放大，以及裁剪超出边界时是报错还是扩展画布。

高风险：不可信输入

文件体积小不代表解码后的像素量小。生产实现应提供像素、页数、解码时间和资源上限；本页在这些限制得到验证前保持草稿状态。

输出必须可以被验证

写出文件后重新读取 Header，至少核对格式、宽高、通道、页数和文件大小，并确认输出能被再次解码。各 binding 对编码参数（质量、插值、色彩空间）的默认值可能不同，因此生产环境应针对每个 binding 显式确认这些参数，而不是假设它们产生相同结果。

观测失败阶段

错误日志应区分 probe、load、normalize、transform、encode 和 verify。同时记录 binding 版本和实际 libvips 版本，避免把 Codec 缺失、输入损坏与参数错误混为一类。

从这里继续

• 先运行15 分钟 Quickstart。
• 用读取、导出与格式转换理解编码边界。
• 用缩放、裁剪、旋转与翻转确定几何操作顺序。
• 用Bands、Alpha 与透明度补上透明图像的风险模型。

来源

• 旧中文手记：src/usage/basic.md、src/usage/transform.md 与 src/usage/color.md，仅用于迁移章节结构和问题清单。
• libvips：How it works
• sharp 输入元数据
• pyvips Introduction