govips 手写 API、vipsgen 生成 API 与惯用模式

govips v2.19.0 通过两层 API 封装 libvips：精心维护的手写函数负责 I/O、导出、流式处理和复杂工作流，自动生成的类型安全 binding 覆盖 193+ 像素级操作。本页解释两者的关系，涵盖 v2.18.0 以来的重大变化（pipeline 包移除、最低 libvips 提升至 8.14、OpenImageRefs 泄漏检测），以及 v2.19.0 新增的流式 I/O（LoadImageFromReader/SaveToWriter/TranscodeStream），以及在生产环境中安全使用 govips 需要掌握的知识。

两层 API

手写函数（Hand-written）

这些函数位于主包中，提供生命周期管理、文件/缓冲区/流 I/O、编解码，以及 GObject 内省代码生成器无法覆盖的便利功能：

类别	关键函数
生命周期	`Startup(nil)`（必须检查错误）、`Shutdown()`、`OpenImageRefs()`、`AssertNoLeaks()`
输入	`NewImageFromFile`、`NewImageFromBuffer`、`NewThumbnailFromFile`、`LoadImageFromReader`、`NewImageFromMemory`
几何	`Resize`、`ExtractArea`、`Similarity`、`Flip`、`Rotate`
颜色	`Modulate`（LCH 色彩空间）
Alpha	`Flatten`、`HasAlpha`、`Bands`
导出	`ExportWebp`、`ExportPng`、`ExportJpeg`、`SaveToWriter`（及其格式特定变体）
流式处理	`TranscodeStream`、`SetPipeReadLimit`、`SetStreamDiscThreshold`
取消	`SetKill`

每个程序必须在任何操作之前调用 vips.Startup(nil) 并检查错误，之后 defer vips.Shutdown()。每个 *vips.ImageRef 使用完毕必须关闭：

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

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

生成操作（Generated Operations）

cmd/vipsgen/ 在构建时读取 libvips GObject 内省数据，生成 generated.go、generated.c 与 generated.h。其中的 vipsGen* 是内部实现；面向使用者的 ImageRef 方法和部分导出函数再对这些实现做类型安全的封装。截至 v2.19.0，覆盖了 193+ 个操作，分布在九个类别：

arithmetic（算术）、colour（颜色）、conversion（转换）、convolution（卷积）、create（创建）、
freqfilt（频域滤波）、histogram（直方图）、morphology（形态学）、resample（重采样）

大多数用户不需要运行代码生成器——它在 govips 开发期间运行。生成的函数编译在 vips 包中，你只需导入即可。如果需要添加对新 libvips 操作的支持，用 go generate ./vips/ 重新生成。

流式 I/O（v2.19.0 新增）

govips v2.19.0 引入了完整的 io.Reader/io.Writer 流式支持：

LoadImageFromReader(r io.Reader, params *ImportParams)：从任意 Reader（HTTP Body、S3 stream、文件句柄）加载图片，不缓冲整个压缩输入。
SaveToWriter(w io.Writer, format ImageType, params *ExportParams)：直接将编码数据写入 Writer。也有格式特定变体（SaveToWriterJpeg、SaveToWriterWebp 等）。
TranscodeStream(r io.Reader, w io.Writer, opts *TranscodeOptions)：一站式 Reader → 解码 → 变换 → 编码 → Writer pipeline。

两种解码策略：

顺序快速路径：无需随机访问时，像素从 Reader 流到 Writer，峰值 RAM 受限于 libvips 行缓存。
实体化路径：需要随机访问时（如 EXIF 旋转），解码帧流式渲染到内存或临时磁盘文件。

out, _ := os.Create("output.jpg")
defer out.Close()

image, _ := vips.LoadImageFromReader(os.Stdin, nil)
defer image.Close()

image.AutoRotate()
image.SaveToWriter(out, vips.ImageTypeJPEG, &vips.ExportParams{Quality: 85})

生产环境生命周期规则

每进程调用一次 Startup，必须检查错误。 初始化 libvips 内部状态。v2.18.0+ 的 Startup 可能返回错误。
Shutdown 一次，务必 defer。 释放全局 libvips 资源。遗漏可能导致内存泄漏。
每个 ImageRef 都要 Close。 每个载入操作分配 libvips 内存。完成后 defer Close() 或显式关闭。
v2.18.0 起可用 OpenImageRefs() / AssertNoLeaks(t)。 开发/测试时追踪未关闭的 ImageRef。
编程错误：关闭后使用图片。 libvips 可能崩溃或返回损坏数据。在 Go 中表现为 panic 或无输出的静默错误。

func process(inputPath string) error {
    image, err := vips.NewImageFromFile(inputPath)
    if err != nil {
        return err
    }
    defer image.Close()

    // 在此处进行操作
    return nil
}

v2.18.0 破坏性变化

pipeline 包已移除。 之前只有约 40 种操作的薄封装，直接使用 ImageRef 方法即可。
最低 libvips 版本从 8.10 提升至 8.14。
ImageRef 拆分为 8 个关注点文件，公共 API 表面不变。
startupIfNeeded 不再 panic，改为返回错误。

内存与性能说明

libvips 使用 GLib 进行内存分配，在高并发下可能产生碎片。两种方式有助于缓解：

MALLOC_ARENA_MAX=2：减少 GLib malloc arena 数量。先尝试此方法。
Jemalloc：替换系统分配器。构建时添加 CGO_LDFLAGS="-ljemalloc"。

两者都不是万能方案——在自己的工作负载上实际测量后再决定采用。

不需要关心的事项

vipsgen 不是独立的 binding，也不是第五个 Tab。它是 govips 的内部代码生成器。除非经过单独评估，否则名称相近的外部项目不在本手册支持范围内。
你的导入路径是 github.com/davidbyttow/govips/v2/vips。生成的代码在同一个包中。
手写函数和生成操作共享相同的 *vips.ImageRef 类型和生命周期——在调用处没有语义上的区分。

已验证版本

govips v2.19.0，libvips 8.17.3（参考版本）。复核日期 2026-10-11。