libvips 的按需执行（Demand-driven）模型

libvips 不是逐行读入、逐行立即处理的传统图像库。它是一个按需执行（demand-driven）的求值引擎——你对图像声明的操作只在真正有人要读取输出像素时才一起执行。这个设计既是 libvips 速度与低内存占用的来源，也是一些常见误解的原因。

构建了 Pipeline，但尚未计算像素

以下代码：

image, err := vips.NewImageFromFile("input.jpg")
if err != nil {
    return err
}
defer image.Close()

if err := image.Resize(0.5, vips.KernelLanczos3); err != nil {
    return err
}
if err := image.GaussianBlur(3.0); err != nil {
    return err
}

文件加载器通常会先读取足以识别格式和元数据的内容，后续调用再构建处理图（Pipeline）：input.jpg → Load → Resize(0.5) → GaussianBlur(3.0) → (等待下游需求)。此时并未完整计算并保存最终像素；导出或写入会从下游向上游按区域请求所需内容。

需求从哪里来

以下情况触发实际求值：

触发动作	说明
ExportJpeg() / ExportWebp() 等	编码器逐行或逐块读取结果
SaveToWriter() / TranscodeStream()	写入目标时逐块请求像素
另一个图像从当前图像读取（composite、join）	下游操作触发上游求值

行缓冲缓存（Line Cache）

libvips 不会一次性把所有中间图像完整缓存在内存中。它会维护一个行缓冲缓存（Line buffer cache）——处理当前请求区域所需的那一小组行。

这意味着：

• 如果你按从上到下的顺序读取（sequential），libvips 只需要保持很少的行在内存中。
• 如果你需要随机访问（例如 90° 旋转需要先读取最后一行），libvips 可能不得不把输入完整缓冲起来，或者在顺序模式下直接报 out of order read 错误。

Sequential 与 Random Access

libvips 支持两种访问模式：

模式	行为	内存峰值
Random（默认）	可以任意顺序读取任何区域	缓存输入所需区域
Sequential	只能从上到下读取一次	主要由图像宽度、操作窗口和编解码器缓冲决定

Sequential 模式需要显式启用（access="sequential" 或 [access=sequential] 选项），并且限制你能做的操作——旋转、垂直翻转等需要非顺序读取的操作会失败。

为什么操作顺序影响内存

// 业务允许在低分辨率上模糊时，可以先缩小。
if err := image.Resize(0.1, vips.KernelLanczos3); err != nil {
    return err
}
if err := image.GaussianBlur(5.0); err != nil {
    return err
}

// 如果业务要求先在原始分辨率上模糊，顺序不能交换，代价也会更高。

先缩小再处理意味着后续所有操作只处理缩小后的像素。这个原则与任何图像库一致，但在 libvips 中尤为重要，因为它决定了整个 Pipeline 在求值时的实际计算量。

常见误解

• 误解 1：“vips.Startup() 在加载图片。” 不，它只初始化 libvips 运行时。
• 误解 2：“图像是在 Close() 前被处理的。” 处理在导出时按需发生；Close() 只是释放图像引用。
• 误解 3：“每个操作都会生成一张完整中间图。” libvips 通常按区域串联求值；是否需要实体化（materialise，即完整解码并缓冲到内存或临时文件）取决于操作的访问模式。
• 误解 4：“按需执行意味着有额外延迟。” 恰恰相反——按需执行让程序只计算实际需要的像素，避免不必要的工作。

风险提示

• Out of Order Read：对 sequential 图像做随机访问操作会报错。
• Cache Miss 惩罚：在大图上的随机访问比顺序访问慢得多。
• 不同入口默认值不同：govips 默认 random；sharp sequentialRead 可配置；pyvips access 可配置。

下一步

了解顺序访问、随机访问与实体化的详细影响和决策点。

来源

• libvips How libvips works
• govips v2.19.0 README Streaming I/O section
• libvips 源码 conversion/sequential.c