术语、错误信息与资料索引

想快速查一个术语、一句报错，或找一个权威出处，可以从这里开始。本页按三部分组织：高频术语、常见错误信息索引与外部资料。

高频术语

术语	定义
libvips	C 编写的高性能图像处理库，通过按需执行（demand-driven）求值与内部线程池在低内存占用下处理超大图像。
按需执行（demand-driven）	先构建处理图（Pipeline），直到导出或下游读取像素时才按区域计算所需像素的执行模型。
实体化（materialisation）	将图像完整解码并缓冲到内存或临时文件，以支持后续随机访问操作。
ImageRef	govips 里持有 libvips VipsImage* 的 CGO 句柄；创建成功后必须显式或通过 defer 调用 Close()。
multi-page / pages	把 GIF、动图 WebP/AVIF、PDF、多页 TIFF 统一建模为多页图像；n=1 只取第一页，n=-1 取全部页。
NumPages	govips 导入参数（ImportParams.NumPages），控制读取多少页或帧。
toilet-roll	动图按整图缩放或旋转时因未加载全部帧或未正确维护 page-height 导致的帧错位现象。
ICC profile	色彩特性配置文件，定义像素值该如何被解释并在跨设备或跨色彩空间转换时保持色彩一致。
CMYK	青、品红、黄、黑四色油墨分量表示法，缩放前需先通过 ICC 转换到工作色彩空间（如 sRGB）。
StripMetadata	导出时是否剥离 EXIF/IPTC/ICC 等元数据；govips 中默认为 false。
EXIF / IPTC	嵌入在图像中的相机参数、方向（Orientation）与版权等元数据。
Alpha 与预乘（Premultiplication）	决定透明度的通道，以及在插值缩放或模糊前用 Alpha 预乘颜色通道以避免暗边的处理步骤。
side-effect import	Go 中仅为了触发包 init() 注册而写的 _ "pkg" 导入；govips v2.19.0 已内置注册 GIF/JPEG/PNG/WebP 解码器，业务代码无需为 govips 重复导入。
comparison-pending	表示跨语言绑定或入口的示例虽然已执行，但像素级结果或默认参数细节尚未做逐项等价断言。

常见错误信息索引

报错或现象	含义与排查入口
VipsJpeg: out of order read	顺序访问（Sequential）输入遇到了垂直翻转、旋转或二次读取等随机访问需求。→ 排查 out of order read
image: unknown format	文件头签名未被 govips 识别（文件截断、动图子格式漏识别），或无原生 loader 回退到 Go 标准库时不支持该格式。→ 未知格式与缺失 Codec
xxxsave not found / xxxload not found	运行时 libvips 版本过旧，或编译时未启用对应的可选编解码库。→ 未知格式与缺失 Codec、安装、链接与 ABI
bad grid geometry / 动图变长图	动图整图变换时未设置 NumPages=-1，或拼接多帧后漏设 SetPageHeight。→ 动画与多页图像
Wrong JPEG library version	编译期链接的 libjpeg 与运行期动态加载的版本冲突。→ 安装、链接与 ABI
并发下偶发段错误 / SIGSEGV	跨 goroutine 共享了非线程安全的 ImageRef，或源图被提前 Close()。→ 并发崩溃与 ImageRef
进程 RSS 持续增长	存在未 Close() 的 ImageRef、缓存尚未封顶或原生分配器碎片。→ RSS 增长与内存泄漏
修改 GIF Quality 无效	原生 gifsave 是调色板编码，不使用 JPEG 式的 Quality，应改用 Effort 与 Bitdepth。→ GIF Quality 不生效
导出后偏色或 WebP 丢失 ICC	CMYK 未先做 ICC 转换，或触发了 WebP 导出丢弃 ICC 的已知边界。→ 色偏、ICC 与 CMYK

外部资料

• 官方 libvips：libvips.org 与 API 文档
• govips：GitHub 仓库 与 Go 包文档
• sharp：官方文档
• pyvips：官方文档
• vips CLI：命令行使用说明
• GLib 内存管理：Memory Slices

使用说明

• 术语定义以官方源码与文档为准；本页提供面向生产排查的快速索引。
• 错误信息索引指向本手册对应的故障排查页面，完整的复现条件与版本边界以各页面正文为准。