常用操作跨 binding 映射
同一产品意图在不同 binding 中 API 命名和参数单位并不相同。govips 是本手册的参考实现；sharp、pyvips 与 CLI 的等价入口用于对照，不代表与 govips 语义逐项一致。
比较边界：下表 govips 列取自 v2.19.0 源码；sharp / pyvips / CLI 列目前标注为比较待定（comparison-pending），不应视为已经过共享 Runner 逐字验证。
| 意图 | govips (v2.19.0) | sharp | pyvips | vips CLI |
|---|---|---|---|---|
| 从文件加载 | vips.NewImageFromFile |
sharp(path) |
pyvips.Image.new_from_file |
vips ... file |
| 从 buffer 加载 | LoadImageFromBuffer |
sharp(buf) |
new_from_buffer |
通过 stdin/文件 |
| 捕获全部页/帧 | importParams.NumPages.Set(-1) |
sharp(input, { pages: -1 }) |
n=-1 参数 |
由 loader 参数控制 |
| 导出到 buffer | ExportWebp(params) / ExportJpeg(params)；流式 SaveToWriter* |
.toBuffer() |
write_to_buffer |
由输出格式驱动 |
| 意图 | govips (v2.19.0) | sharp | pyvips | vips CLI |
|---|---|---|---|---|
| 按尺寸缩放 | NewThumbnailWithSizeFromFile / LoadThumbnailFromFile |
.resize(w,h,{fit}) |
thumbnail / resize |
vips thumbnail |
| 相对倍数缩放 | Resize(scale, kernel) / ResizeWithVScale(h, v, kernel) |
.resize(factor) |
resize(scale) |
vips resize |
| 旋转 | Rotate(angle)（角度枚举） |
.rotate(angle) |
rotate(angle) |
vips rot |
| 翻转 | Flip |
.flip() |
flip(axis) |
vips flip |
| 裁剪 | ExtractArea |
.extract() |
crop() |
vips crop |
| 意图 | govips (v2.19.0) | sharp | pyvips | vips CLI |
|---|---|---|---|---|
| 叠加合成 | Composite / ArrayJoin |
.composite() |
composite() |
vips composite |
| 色彩变换 | TransformICCProfile（含 TransformICCProfileWithFallback） |
.toColourspace() |
colourspace() |
vips colourspace |
| 画质/解码参数 | ImportParams |
内置于 loader | 参数传递 | CLI 的 loader 参数 |
- 单位差异：
Resize的 scale 是相对倍数（1.0 表示 100%），而Thumbnail/shrink是按目标尺寸。不要用sharp.resize(w,h)的语义去理解 govips 的Resize。 - 加载/缩放路径：
Thumbnail*走 libvips 的按目标尺寸只解码所需部分的路径，与先加载整幅再缩放的路径不同。 - 动图：见故障排查 animation-multi-page，缩放/旋转动图需先加载全部页。
来源与证据边界
Section titled “来源与证据边界”- govips v2.19.0 源码（
NewImageFromFile、LoadImageFromBuffer、NumPages、NewThumbnailWithSizeFromFile、Resize/ResizeWithVScale、Rotate、Flip、ExtractArea、Composite、TransformICCProfile、ExportWebp）。 - sharp / pyvips / CLI 列尚未经共享 Runner 逐字验证，标注 comparison-pending。
以上映射以满足产品意图为准；具体参数默认值详见各 binding 文档，并以本手册锁定的参考基线为准。